Data models

Data models describe the structure of the data files stored as JSON, TOML or YAML files. Common examples might be a data/footer.json that contains the site's footer configuration or authors.json that contains list of blog post authors.

Data Models extend the common properties defined in the base Model.

Data Model Properties

In addition to the common properties, data models define the following properties:

• 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.
• isList: boolean flag specifying if the data described by this model stored as list object.

Examples

Data with list file

Take the following site structure

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

The data in the data/authors.json file

[
  {
    "first_name": "John",  
    "last_name": "Doe"  
  },
  {
    "first_name": "Jane",  
    "last_name": "Doe"  
  }
]

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"
    }
  ]
}

These files and their content could be described in the following way:

stackbitVersion: ~0.3.0
...
dataDir: data
models:
  author:
    type: data
    label: Author
    file: authors.json  # path is relative to the `dataDir`
    isList: true
    items:
      type: object
      fields:
        - type: string
          name: first_name
        - type: string
          name: last_name
  features:
    type: data
    label: Footer
    file: footer.json  # path is relative to the `dataDir`
    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 the 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 the path to that folder. 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:
      ...