SideDoc

Appearance

Adding a profile ​

A new profile needs a sheet tab, a generation step in the build, a help file and, if it is exported, a mapping. The editor picks it up from the version bundle; no app change is needed to show it.

1. Create the sheet tab ​

Add a tab with the same columns as the other profile tabs (see sheet columns). scripts/create_catalog_sheet_tab.py shows how the NDE catalog tab was made from the NDE dataset tab's header row.

  • Pick a new id prefix for the profile, for example myp:. Field ids then start with it; the lints treat ids with other prefixes as belonging to other profiles.
  • Add one root row with datatype Class. Its id is the profile id (myp:v00001), its class is the class name used on every row, and label_singular_en is the name shown in the editor's profile picker.
  • Add the fields under it (Adding a field).

2. Add it to the build ​

In build.sh:

  1. Add the tab's gid next to the other *_GID variables and a URL variable next to the other schema URLs.

  2. Add a generation step like the NDE one:

    sh
    python3 schemaGen.py \
  --sheet-id "$SHEET_ID" --gid "$MY_PROFILE_GID" "${SCHEMA_GEN_AUTH_ARGS[@]}" \
  --mode doc --id "$BASE_URL/my-profile.json" \
  --import-schema "$OUTPUT_DIR/type-library.json" \
  -o "$OUTPUT_DIR/my-profile.json"

  3. Add cp "$OUTPUT_DIR/my-profile.json" "$DEPLOY_DIR/" to the deploy step. The help files are copied with docs.*.json already.

Also add the tab to TABS in scripts/snapshot_source_tabs.py and a matching step to build-local.sh, so the version can be rebuilt offline from versions/<version>/my-profile.tsv.

The schema lint, the help step and the reference generator find the new schema in output/ by themselves.

Vocabulary embedding

build.sh embeds vocabulary bindings into datasheet.json only (build-local.sh also into cmdi-data-envelope.json). For other profiles the app applies field-attachments.json from the bundle at run time. If the new profile should carry its bindings in the schema, add an embed_vocab_in_schema.py call for it.

3. Write the help ​

The first build creates help/docs.my-profile.json with an empty entry per field. Write the general block (title, short and extended text about the profile; the reference page uses it as the introduction) and the field texts. See Writing help texts.

To let a profile use another profile's help file, set x-sidedoc.docsSchemaUrl to that file in its schema, as build.sh does for Datasheet v2 (docs.datasheet.json). The help step then merges the field ids of both profiles into one file.

4. Exports (optional) ​

  • Write rdf-targets/dcat-ap/my-profile.dcat-ap.mapping.json with "sourceProfileId": "my-profile" (the schema file name without .json). The help step uses sourceProfileId to find the profile.
  • To declare export formats in the schema, add x-exports at the root, as the NDE catalog step in build.sh does (["dcat-ap-3.0.1"]).

To verify

The backend has one exporter per profile (document-to-jsonld.ts for the datasheet, document-to-dcat-ap-jsonld.ts for DCAT-AP), each importing its own mapping file. A new mapping file is copied into the backend by sync-dcat-mappings.mjs, but it is not clear that it is used without a matching exporter in the backend.

5. Converting an existing profile ​

The Data Envelope profile was converted from a CLARIN CMDI component specification by scripts/convert_cmdi_profile.py (sources in cmdi-source/). The converter writes the profile TSV to versions/<VERSION>/ (override with --version), one SKOS vocabulary per enumerated field and the field attachments. It also merges the CMDI labels and explanations into help/docs.cmdi-data-envelope.json: they only fill empty English texts, so help that has been written or edited is kept. Use it as a model for other external profiles. build.sh and build-local.sh then build the profile from the TSV like the others.

6. Publish ​

Publish as part of a new version (Versioning and publishing). After the bundle is in the app's public/schemas/<version>/, run scripts/build_versions_manifest.py: the profile appears in versions.json and in the editor. The reference page appears after the next run of gen_profile_docs.py.