Data models

Data models describe data files formatted using either JSON, TOML or YAML. Common examples might be a data/footer.json that contains the site's footer configuration or config.toml that contains site's configuration options.

Data Models share the common model properties.

In addition to common properties, data models have the following properties with similar behavior as in Page Models:

• file: path to the data file relative to the dataDir folder. Cannot be combined with folder, match and exclude matching options.
• folder: path to the folder, relative to the dataDir folder, containing the data files. The default value for folder is an empty string, matching all data files in dataDir. This value can be combined with the match and exclude options to fine tune the files to match.
• match: specifies which files to match, defaults to **/* which matches all files. The match is executed in the context of the folder.
• exclude: specifies which files to exclude from the match, defaults to unset value which does not exclude anything. The exclude is executed in the context of the folder.

Example

Take the following site structure

├── content
│   └── posts
│       ├── post1.md
│       └── post2.md
├── data
│   └── footer.json
└── stackbit.yaml

The data in the data/footer.json file

{
  "features": [
    {
      "title": "Free Consultation",
      "description": "New clients recieve an obligation free consultation.",
      "image": "images/features/noun_branding_1885335.svg"
    },
    {
      "title": "Certified Accountants",
      "description": "All members of our team are certified accountants.",
      "image": "images/features/noun_The Process_1885341.svg"
    },
    {
      "title": "Tax Compliance",
      "description": "We stay up to date on the latest changes to the tax code.",
      "image": "images/features/noun_3d modeling_1885342.svg"
    }
  ]
}

Would map to the following data model in the stackbit.yaml:

dataDir: data
models:
  features:
    type: data
    label: Footer
    file: footer.json  # path is relative to the `dataDir` which is `data`
    fields:
      - type: list
        name: features
        items:
          type: object
          label: Feature
          labelField: title
          fields:
            - type: string
              name: title
              label: Title
            - type: string
              name: description
              label: Description
            - type: image
              name: image
              label: Icon

Data in root folder

In case your site has data files scattered across several folders, or if it has data files in the root folder, you can set dataDir to an empty string and specify file relative to the root folder.

├── data
│   └── footer.json
├── stackbit.yaml
└── config.yaml

stackbit.yaml:

stackbitVersion: ~0.3.0
...
dataDir: ""
models:
  config:
    type: data
    label: Config
    file: config.yml  # relative to `dataDir` which is the root folder
    fields:
      ...
  footer:
    type: data
    label: Footer
    file: data/footer.json  # relative to `dataDir` which is the root folder
    fields:
      ...

Data collections

If your site has multiple data files of the same model located in the same folder, use the folder property to specify that folder path. This pattern can be useful when referencing data files from reference fields.

├── data
│   ├── authors
│   │   ├── john.yml
│   │   └── jane.yml
│   └── footer.json
├── stackbit.yaml
└── config.yaml

stackbit.yaml

stackbitVersion: ~0.3.0
...
dataDir: 
models:
  config:
    type: data
    label: Config
    file: config.yml
    fields:
      ...
  footer:
    type: data
    label: Footer
    file: data/footer.json
    fields:
      ...
  author:
    type: data
    label: Author
    folder: data/authors
    fields:
      ...