99 lines
2.9 KiB
Markdown
99 lines
2.9 KiB
Markdown
#level/hardcore
|
||
|
||
> **warning** Warning
|
||
> This feature is **experimental**, it may evolve over time.
|
||
|
||
SilverBullet allows you to define schema for custom [[Space Config]] settings as well as for [[Objects|object]] [[Tags|tags]]. Both are defined using [[Space Config]] and use a [[YAML]] encoding of [JSON Schema](https://json-schema.org/).
|
||
|
||
# Object Schemas
|
||
The general format to define schemas for specific [[Tags]] is as follows:
|
||
|
||
~~~
|
||
```space-config
|
||
schema.tag.<<TAG>>: <<JSON SCHEMA ENCODED AS YAML>>
|
||
```
|
||
~~~
|
||
|
||
## Example
|
||
Let’s say you use pages tagged with `#contact` to represent your contacts:
|
||
|
||
```template
|
||
{{#each {contact}}}
|
||
* [[{{name}}]] ([{{email}}](mailto:{{email}})):
|
||
* First name: _{{firstName}}_
|
||
* Last name: _{{lastName}}_
|
||
{{/each}}
|
||
```
|
||
|
||
To ensure you always attach the required meta data in [[Frontmatter]] for your contacts, you’d like to do some checking. Specifically you would like to enforce that:
|
||
|
||
* `firstName` should always be a `string` and is _required_
|
||
* `lastName` should always be a `string` and is _required_
|
||
* `email` should be an e-mail address, if specified
|
||
|
||
You can achieve this using the following [[Space Config]]:
|
||
|
||
```space-config
|
||
schema.tag.contact:
|
||
properties:
|
||
firstName.type: string
|
||
lastName.type: string
|
||
email:
|
||
type: string
|
||
format: email
|
||
required:
|
||
- firstName
|
||
- lastName
|
||
```
|
||
|
||
> **note** Note
|
||
> To reload changes to your schema, be sure to run {[System: Reload]}
|
||
|
||
# Config schema
|
||
[[Space Config]] allows you to define arbitrary configuration keys for your own use cases. This is primarily useful for [[Libraries]], but perhaps you find your own use cases too.
|
||
|
||
The general format is:
|
||
|
||
~~~
|
||
```space-config
|
||
schema.config: <<JSON SCHEMA ENCODED AS YAML>>
|
||
```
|
||
~~~
|
||
|
||
## Example
|
||
Let’s say you find it useful to make your full name globally configurable:
|
||
|
||
```space-config
|
||
myFullName: "Steve Hanks"
|
||
```
|
||
|
||
This can be useful, because you can reference this configuration key in any query or template, e.g.:
|
||
|
||
```template
|
||
My full name is: {{@config.myFullName}}
|
||
```
|
||
|
||
However, you would like to make sure that this `myFullName` configuration is always a string. You can achieve this with the following config schema definition:
|
||
|
||
```space-config
|
||
schema.config.properties.myFullName.type: string
|
||
```
|
||
|
||
Now, if you would accidentally change `myFullName` into a number or boolean value, you would get a validation error.
|
||
|
||
# Validation
|
||
At the moment, validation only occurs in the editor in [[Space Config]] and [[Frontmatter]] blocks and shows any violations as highlighted errors.
|
||
|
||
Even if data does not pass validation, it is still stored in the data store so it does not (currently) _enforce_ the format.
|
||
|
||
This may change in the future.
|
||
|
||
# Supported types
|
||
All standard JSON Schema types are supported. Likely you are interested in:
|
||
* `string`
|
||
* With custom formats (specified via `format`):
|
||
* `email`
|
||
* `page-ref` (for page references, e.g. `[[something]]`)
|
||
* `number`
|
||
* `array`
|
||
* `object` |