x-sidedoc keys

The x-sidedoc object that the schema generator (GenJSONSchema/schemaGen.py) and the build attach to profile roots and fields. It carries what plain JSON Schema cannot: field ids, labels, cardinality as written in the sheet, editor hints and vocabulary bindings. The editor and the docs generator read it; validators ignore it. Each key notes its source in x-source and where it appears in x-scope (root: the profile itself; field: any property; branch: a copy on a oneOf branch). Keys marked deprecated are read by the editor as fallbacks but no generator writes them.

Source: GenJSONSchema/x-sidedoc.schema.json in the schemas repository. scripts/schema_lint.py checks every x-sidedoc block in the generated schemas against it. Counts are for the 0.2.4 bundle.

Key	Value	Where	Set from	Blocks
id	string	root, field	sheet column id	952
labelSingularEn	string	root, field	sheet column label_singular_en	952
labelPluralEn	string	field	sheet column label_plural_en (only written when filled in)	472
type	string	field	sheet column datatype	598
unionTypes	array of string	field	sheet column datatype, when it contains |	36
minOccurrences	integer	field	sheet column min_occurrences (empty = 0)	945
maxOccurrences	integer	field	sheet column max_occurrences (empty = 0)	945
multilingual	boolean	root, field	sheet column multlingual (TRUE/FALSE)	952
optionalFreeText	boolean	root, field	sheet column optional_free_text	952
uiHint	text, fixed list	field	sheet column ui_hint	321
isTitle	always true	field	sheet column ui_hint = title	2
validationPattern	string	field	sheet column validation_pattern	149
allowedSchemas	array of objects	field	sheet column allowed_schemas (JSON array), or extra_conf {"identifier": {"allowedSchemas": [...]}}	25
caption	string	field	sheet column extra_conf	21
dateMode	text, fixed list	field, branch	sheet column extra_conf	2
vocab	object	field	vocabs/field-attachments.json, via compile_skos_vocab.py and embed_vocab_in_schema.py	49
version	string	root	schemaGen.py --id	6
docsSchemaUrl	string	root	build.sh (postprocess_docs_schema.py --docs-url, and the datasheet-v2 step)	6
helpTextsUrl	string	root	build.sh	6
rootClass	string	root	schemaGen.py --mode document	0
allowCustomTerm	boolean	field	extra_conf sub-field override (no published profile uses it)	0

id

Stable field id, prefix:code. The prefix names the profile (ds: datasheet, nde:, dcatap:, cmdi:, sd: type library). Help files, mappings and documents refer to fields by this id, so never reuse or renumber one. Root ids use v (ds:v00003), field ids f or t.

• Value: string
• Pattern: ^[a-z][a-z0-9-]*:[A-Za-z0-9_.-]+$
• Where: root, field
• Set from: sheet column id
• Blocks in this bundle: 952
• Example: "ds:f00100"
• Example: "ds:v00003"
• Example: "sd:t02000"

labelSingularEn

English field label, shown in the editor and used as the help and docs title. On the root it is the profile name shown in the profile picker.

• Value: string
• Where: root, field
• Set from: sheet column label_singular_en
• Blocks in this bundle: 952
• Example: "Title"
• Example: "Datasheet v2.1"

labelPluralEn

English plural label, used for repeatable fields (list headings, Add buttons).

• Value: string
• Where: field
• Set from: sheet column label_plural_en (only written when filled in)
• Blocks in this bundle: 472
• Example: "Keywords"

type

SideDoc datatype of the field: a type-library type (Literal, RichText, Term, Url, Agent, ...) or Container for a group of sub-fields. For a union datatype this is the first type; see unionTypes. Not written for JSON.string and JSON.object.

• Value: string
• Where: field
• Set from: sheet column datatype
• Blocks in this bundle: 598
• Example: "Literal"
• Example: "Agent"
• Example: "Container"

unionTypes

All datatypes of a union field (datatype written as A|B). The user picks one type per field, and the editor shows a type toggle.

• Value: array of string
• Where: field
• Set from: sheet column datatype, when it contains |
• Blocks in this bundle: 36
• Example: ["Term", "Literal"]
• Example: ["Agent", "Url"]

minOccurrences

Minimum number of values. 1 or more makes the field required.

• Value: integer
• Where: field
• Set from: sheet column min_occurrences (empty = 0)
• Blocks in this bundle: 945
• Example: 0
• Example: 1

maxOccurrences

Maximum number of values. -1 means no limit; 1 makes the field single-valued. 0 (an empty cell) is treated as no limit by the generator.

• Value: integer
• Where: field
• Set from: sheet column max_occurrences (empty = 0)
• Blocks in this bundle: 945
• Example: 1
• Example: -1

multilingual

The value can be given in several languages. Literal, RichText, Enum, Term, Agent and Reference carry their languages inside the value, so for those types the flag does not change the JSON shape; for other types the generator wraps the value in an array of language variants.

• Value: boolean
• Where: root, field
• Set from: sheet column multlingual (TRUE/FALSE)
• Blocks in this bundle: 952
• Example: true

optionalFreeText

Instead of the structured value the user may write free text. The schema then has a oneOf of the structured type and RichText (or Literal, see the sheet column). The editor shows a toggle.

• Value: boolean
• Where: root, field
• Set from: sheet column optional_free_text
• Blocks in this bundle: 952
• Example: false

uiHint

Editor hint for how to render or check the field. url and email switch a Url field between web and mail mode; multiline gives a Literal a text area; identifier and identifier_agent give a TypedValue the identifier picker (identifier_agent also offers person and organisation schemes); doi gives a TypedValue the DOI mode; date_picker, datetime_picker and year set the input format; enum_lookup, enum_select and term_lookup choose the vocabulary picker; link_dataset and link_catalog give a Url field a picker of the dataset or catalog documents in the workspace. The value title in the sheet is not written here; it becomes isTitle.

• Value: one of url, email, date_picker, datetime_picker, year, enum_lookup, enum_select, term_lookup, identifier, identifier_agent, language_code, checksum, multiline, bibtex, doi, text, link_dataset, link_catalog
• Where: field
• Set from: sheet column ui_hint
• Blocks in this bundle: 321
• Example: "url"
• Example: "term_lookup"
• Example: "multiline"

isTitle

Marks the document's main title field. The editor shows it in the large header style.

• Value: always true
• Where: field
• Set from: sheet column ui_hint = title
• Blocks in this bundle: 2
• Example: true

validationPattern

The validation pattern as written in the sheet, kept for display. The generator also writes it as a JSON Schema pattern, on the field itself (/regex/, only for JSON.string fields) or on sub-fields ({"href": "/regex/"} or href=/regex/). Slashes delimit the regex.

• Value: string
• Where: field
• Set from: sheet column validation_pattern
• Blocks in this bundle: 149
• Example: "{\"href\":\"/^https?:\\\\/\\\\/.+$/\"}"
• Example: "/^\\d{4}(-\\d{2}(-\\d{2})?)?$/"

allowedSchemas

Identifier schemes the user can pick for a TypedValue (identifier) field. Set on the field directly, or on the identifier sub-field of an inlined Agent through extra_conf.

• Value: array of objects
• Where: field
• Set from: sheet column allowed_schemas (JSON array), or extra_conf {"identifier": {"allowedSchemas": [...]}}
• Blocks in this bundle: 25
• Example: [{"uri": "https://orcid.org/", "label": "ORCID"}, {"uri": "https://ror.org/", "label": "ROR"}]

caption

Template for the one-line summary of a collapsed row in a list of complex values. {name} placeholders are replaced by the plain text of that sub-field.

• Value: string
• Where: field
• Set from: sheet column extra_conf
• Blocks in this bundle: 21
• Example: "{distributionTitle}"
• Example: "{name} ({role})"

dateMode

Locks a Date field to a single date or to an interval and hides the toggle. Without it the user can choose. Copied onto the array branch of a free-text union, because the editor renders that branch.

• Value: one of single, interval
• Where: field, branch
• Set from: sheet column extra_conf
• Blocks in this bundle: 2
• Example: "single"

vocab

Vocabulary binding: which SKOS concept schemes the field takes terms from and how strictly. Embedded by scripts/embed_vocab_in_schema.py from vocabs/field-attachments.json (datasheet and CMDI profiles; other profiles get the binding at run time from field-attachments.json next to the schema).

• Value: object
• Where: field
• Set from: vocabs/field-attachments.json, via compile_skos_vocab.py and embed_vocab_in_schema.py
• Blocks in this bundle: 49
• Example: {"kind": "term", "schemes": ["https://spdx.org/licenses/"], "enforcement": {"schema": "closed", "value": "open"}, "allowCustomLabel": true}

Sub-key	Value	Meaning
kind	one of term, scalar	term: the value is a Term (URI plus label). scalar: the value is a plain code from the scheme, such as a language code.
schemes	array of string	Concept scheme URIs, as in vocabs/skos/*.jsonld.
enforcement	object
enforcement.schema	one of open, closed	closed: only the listed schemes. open: terms from other schemes are accepted.
enforcement.scheme	one of open, closed	Alias of schema, accepted by the backend.
enforcement.value	one of open, closed	closed: only concepts from the schemes. open: the user can type a value of their own.
allowCustomLabel	boolean	The user may type a label that is not in the vocabulary (for Enum fields: a custom option).

version

Datamodel version of the profile, taken from the version segment of the $id (0.2.2 in https://sidedoc.app/schemas/0.2.2/datasheet.json). Documents record it to know which schema they were written against.

• Value: string
• Pattern: ^\d+\.\d+\.\d+$
• Where: root
• Set from: schemaGen.py --id
• Blocks in this bundle: 6
• Example: "0.2.2"

docsSchemaUrl

Help file for this profile when it is not docs.<schema file name>. Only the file name is used; it is loaded from the same bundle. datasheet-v2 uses it to share docs.datasheet.json.

• Value: string
• Where: root
• Set from: build.sh (postprocess_docs_schema.py --docs-url, and the datasheet-v2 step)
• Blocks in this bundle: 6
• Example: "/schemas/docs.datasheet.json"

helpTextsUrl

Older name for the help file, used as a fallback when docsSchemaUrl is missing. Points at the generic help-texts.json.

• Value: string
• Where: root
• Set from: build.sh
• Blocks in this bundle: 6
• Example: "/schemas/help-texts.json"

rootClass

Root class name in a thin document schema (schemaGen.py --mode document). No published profile uses this mode.

• Value: string
• Where: root
• Set from: schemaGen.py --mode document
• Blocks in this bundle: 0
• Example: "Datasheet"

allowCustomTerm

Set to false to stop the user from adding a term of their own in a Term field that has a vocabulary. Read by the editor; not written by the generator, but can be set on a sub-field through extra_conf.

• Value: boolean
• Where: field
• Set from: extra_conf sub-field override (no published profile uses it)
• Blocks in this bundle: 0
• Example: false

Fallback keys

The editor also reads these keys, as fallbacks. No generator writes them; do not add them to new schemas.

Key	Meaning
label	Fallback label read by the editor. Use labelSingularEn.
labelSingular	Fallback label read by the editor. Use labelSingularEn.
labelEn	Fallback label read by the editor. Use labelSingularEn.
labelPlural	Fallback plural label read by the editor. Use labelPluralEn.
urlKind	Fallback for uiHint on Url fields (a value containing mail switches to email mode).
inputKind	Fallback for uiHint on Url fields.
inputType	Fallback for uiHint on Url fields.
formatHint	Fallback for uiHint on Url fields.
help	Inline help fallback read by the editor. Write help in help/docs.<profile>.json instead.
helpText	Inline help fallback read by the editor. Write help in help/docs.<profile>.json instead.
helpShort	Inline help fallback read by the editor. Write help in help/docs.<profile>.json instead.