SideDoc

Appearance

Profiles and schemas ​

A profile is the set of fields one kind of document has: which fields exist, how they nest, which type each value has, how many values are allowed, and which vocabularies apply. SideDoc ships each profile as a JSON Schema. The editor builds its form from that schema, validates documents against it, and shows help texts written for it.

The schemas live in their own repository (gitlab.com/sidedoc/schemas). This section explains how they are made and how to change them. The reference lists every field of every profile.

Profiles ​

Version 0.2.4 has these profiles. The file name is also the page name in the reference.

ProfileIdFilePurposeBased on
Datasheet v2.1ds:v00003datasheet.jsonThe current datasheet: describes a cultural heritage dataset for reuse, for example in AI and machine learning. The default for new documents.Datasheet template v2 (Zenodo)
Datasheet v2ds:v00002datasheet-v2.jsonThe earlier datasheet structure, frozen. Built from the 0.1.2 snapshot so older documents stay editable. Shares its help texts with Datasheet v2.1.Datasheet template v2 (Zenodo)
NDE Datasetbeschrijvingnde:v00001nde-dataset-description.jsonA dataset description that meets the requirements of the Dutch Network Digital Heritage (NDE), based on DCAT-AP-NL 3.0.NDE requirements
NDE Catalogusbeschrijvingnde:v00002nde-data-catalog-description.jsonA data catalog description for the NDE dataset register.NDE requirements
DCAT-AP 3.0.1 Datasetdcatap:v00001dcat-ap-dataset.jsonA dataset description following the EU DCAT-AP 3.0.1 standard.DCAT-AP 3.0.1
Data Envelope v1cmdi:v00001cmdi-data-envelope.jsonA port of the CLARIN CMDI Data Envelope profile.CLARIN CMDI profile
Type librarytype-library.jsonNot a profile: the reusable value types (Literal, Agent, Term, ...) that all profiles use.

The app reads the list of profiles per version from public/schemas/versions.json, so a profile appears in the editor once its schema is in the version bundle.

How the parts fit together ​

text
Google Sheet (one tab per profile)            help/docs.<profile>.json (hand-written)
  │  snapshot: versions/<ver>/*.tsv                │
  ▼                                                │
schemaGen.py ──► type-library.json                 │
             └─► <profile>.json  ◄── vocab bindings (vocabs/field-attachments.json,
                       │                            vocabs/skos/*.jsonld)
                       │
postprocess_docs_schema.py ◄───────────────────────┘
  ├─► help/docs.<profile>.json   (new field ids added, labels and paths refreshed)
  └─► output/docs.<profile>.json (published copy + mappings from rdf-targets/)
                       │
gen_profile_docs.py ──► docs/profiles/reference/<ver>/*.md (this site)
  • Schema. Generated from the sheet by GenJSONSchema/schemaGen.py. Each field gets an x-sidedoc block with its id, labels, cardinality and editor hints; see x-sidedoc keys and sheet columns.
  • Type library. The value types. A profile field refers to a type with $ref; the type library is generated from the sheet's SideDoc tab.
  • Help texts. Not in the sheet. They are JSON files in help/, keyed by field id. See Writing help texts.
  • Vocabularies. SKOS concept schemes in vocabs/skos/, bound to fields in vocabs/field-attachments.json. See Vocabularies.
  • Mappings. How fields are exported to RDF, in rdf-targets/<target>/<profile>.<target>.mapping.json. The backend export uses them; the help build copies the target property of each field into the help, so the editor can show "In exports: dcterms:title".

Field ids (ds:f00100) tie everything together: help entries, mapping rules and links from the editor to this reference all use them. Never change or reuse an id.

Tasks ​