Skip to content

Latest commit

 

History

History
50 lines (39 loc) · 2.88 KB

file_format.md

File metadata and controls

50 lines (39 loc) · 2.88 KB
Raw

File format

Here is an example of json file with information about some Home Assistant card:

{
    "card_id" : "af4684002036",
    "image" : "https://upload.bessarabov.ru/bessarabov/QjyEHqSWitD1m2V3CuUdJNNFGBo.png",
    "name" : "animated-consumption-card",
    "repo" : {
        "clone_url" : "https://github.com/bessarabov/animated-consumption-card.git",
        "type" : "github"
    },
    "site" : "https://github.com/bessarabov/animated-consumption-card",
    "status" : "active",
    "tags" : [
        "consumption"
    ]
}
Field Description
card_id This is the main id for the card. It is unique. It is autogenerated. There is no hidde info in it, it is just a random string. The length if always 12. In this string there can by only digits from 0 to 9 and lowercase letters from "a" to "f".
site The url with the info about this card created by the author. Usually it is a link to GitHub repo. There can be situations when several cards have the same site, when there is one page with information about several cards, but this situation is seldom.
name The name of the card. This is always the string that is used when the card is added to Home Assistant UI (- type: 'custom:animated-consumption-card') but without custom:. There can be situations where two or more cards have the same name. For example an original card and a popular fork.
status The string active, deprecated or deleted. Status deprecated is used only when there is information in thre repositorey that this project is deprecated and/or the GitHub repo is archived. If there is no such info in the repo the status stays active, even if there is no recent commits.
image Url with the card sample image. The format must be png. This field is optional.
repo This is an optinal field. The value is the json object with data about the repo. In that object there must be field type. Other fields in the objects depends of the type. Now there is only one possible type: github, but in the future other types can be introduced.
tags This is an optinal field. The value is the json array with strings.

repo with type github

"type" : "github" means that the source code for this card is sotred in GitHub repo and there is only one UI card in that repo.

Field Description
type github
clone_url This is a direct url that can be used in git clone command. It should be https url, not git url.

Note about file paths

The path for the json file is generated from card_id.

Card with card_id af4684002036 is stored in this repo at data/a/f/4684002036.json. Under the data/ folder there are subfolder by first & second symbol from card_id.

Such file structure is chosen to prevent storing a lot of files in one folder.

This idea was borrowed from the way version control system git stores its data.