Curie to Uri and documentation addition

config.yaml

@@ -57,6 +57,7 @@ generator_args:
   shacl:
     mergeimports: true
     use_class_uri_names: false
+    closed: false
   shex:
     mergeimports: true
   sqlddl:

docs/working-with-data.md

@@ -0,0 +1,120 @@
+# Working with Data in Chem-DCAT-AP
+
+This page explains how to create and validate data that conforms to the Chem-DCAT-AP schema, and what you need to be aware of before you start.
+
+## What you get from the schema
+
+The Chem-DCAT-AP schema (`chem_dcat_ap.yaml`) is the single source of truth. From it, the following artefacts are automatically generated and published alongside the schema:
+
+| Artefact | File | What it is for |
+|---|---|---|
+| **JSON Schema** | `project/jsonschema/chem_dcat_ap.schema.json` | Validate Chem-DCAT-AP data in JSON/YAML format with any JSON Schema-compatible tool |
+| **SHACL shapes** | `project/shacl/chem_dcat_ap.shacl.ttl` | Validate RDF data in a triplestore |
+| **Python dataclasses** | `src/chem_dcat_ap/datamodel/chem_dcat_ap.py` | Work with Chem-DCAT-AP data objects in Python |
+| **Pydantic models** | `src/chem_dcat_ap/datamodel/chem_dcat_ap_pydantic.py` | Type-safe Python data handling with automatic validation |
+| **JSON-LD context** | `project/jsonld/chem_dcat_ap.context.jsonld` | Convert JSON/YAML data to linked data |
+
+Because all of these are generated from the same source, they are always coherent with each other.
+
+## Writing your first dataset
+
+Chem-DCAT-AP data files can be written in YAML or JSON. A minimal dataset looks like this:
+
+```yaml
+id: https://doi.org/10.14272/UGRXAOUDHZOHPF-UHFFFAOYSA-N/CHMO0000595.1
+title:
+  - 13C nuclear magnetic resonance spectroscopy (13C NMR)
+description:
+  - Dataset for 13C nuclear magnetic resonance spectroscopy (13C NMR)
+was_generated_by:
+  - id: https://doi.org/10.14272/UGRXAOUDHZOHPF-UHFFFAOYSA-N/CHMO0000595.1#DataGeneratingActivity
+    description:
+      - The analysis of the spectrum generated by a 13C nuclear magnetic resonance spectroscopy
+```
+
+More complete examples — including provenance graphs with instruments, samples, and measured quantities — can be found in the [`examples/output/`](examples/output) directory.
+
+## Validating and converting data
+
+LinkML provides command-line tools for validating and converting your data files.
+
+**Validate** a YAML or JSON file against the schema:
+
+```bash
+linkml-validate -s src/chem_dcat_ap/schema/chem_dcat_ap.yaml my-dataset.yaml
+```
+
+**Convert** YAML/JSON to RDF (Turtle):
+
+```bash
+linkml-convert -s src/chem_dcat_ap/schema/chem_dcat_ap.yaml -t ttl my-dataset.yaml -o my-dataset.ttl
+```
+
+**Convert** YAML to JSON (or vice versa):
+
+```bash
+linkml-convert -s src/chem_dcat_ap/schema/chem_dcat_ap.yaml -t json my-dataset.yaml -o my-dataset.json
+```
+
+For a full list of supported formats and options, see the [LinkML data documentation](https://linkml.io/linkml/data/index.html).
+
+---
+
+## Known limitations
+
+### Use full URIs, not CURIEs, for ontology terms
+
+When referencing ontology terms — for example in `rdf_type` — you should use **full URIs** rather than CURIEs (prefixed short-forms like `OBI:0000566`).
+
+!!! warning "Unknown prefixes cause validation errors"
+    If you use a CURIE whose prefix is not defined in the Chem-DCAT-AP prefix map, the LinkML tools will throw an error during conversion or validation. For example:
+
+    ```yaml
+    rdf_type:
+      id: OBI:0000566   # ❌ fails if OBI is not in the prefix map
+    ```
+
+    ```yaml
+    rdf_type:
+      id: http://purl.obolibrary.org/obo/OBI_0000566   # ✓ always works
+    ```
+
+    The Chem-DCAT-AP prefix map already includes a number of common prefixes, but it cannot cover every ontology in use across the chemical sciences. If you need to rely on CURIEs in your data, you can pass additional prefix declarations on the command line:
+
+    ```bash
+    linkml-convert -s chem_dcat_ap.yaml \
+      --prefix MY=https://my-ontology.example.org/ \
+      -t ttl my-dataset.yaml
+    ```
+
+    Alternatively, extend the schema locally and add the missing prefix under the `prefixes:` block. See [how-to-extend.md](how-to-extend.md) for guidance on creating a local profile.
+
+### Chem-DCAT-AP uses a closed-world model — additional properties are not permitted
+
+Chem-DCAT-AP is built on LinkML, which validates data under a **closed-world assumption**: any property or relation not explicitly defined in the schema is rejected during validation. This is true for most generated artefacts — JSON Schema, Pydantic models, and Python dataclasses all enforce this strictly. SHACL shapes are an exception and have been configured to remain open, in closer alignment with how DCAT-AP itself operates.
+
+In practice, this matters most in two scenarios:
+
+**Adding chemistry-specific properties beyond what Chem-DCAT-AP defines.** If your data includes relations or attributes that are meaningful in your domain but not currently modelled in the schema — custom measurement parameters, domain-specific provenance links, instrument metadata, and so on — validation will fail. This is the most common friction point for Chem-DCAT-AP users, since the schema deliberately covers a focused set of properties and real-world datasets often have richer descriptions.
+
+**Bringing in data from other application profiles.** If you are working with existing DCAT-based data from another profile (e.g. GeoDCAT-AP or BioDCAT-AP), properties defined there but absent from Chem-DCAT-AP will likewise be rejected.
+
+If you run into either situation, the recommended path is:
+
+- **Open an issue** if you believe the missing property belongs in the core Chem-DCAT-AP schema. The schema is actively maintained and extensions are considered.
+- **Create a local subprofile** if your needs are specific to your project or organisation. See [how-to-extend.md](how-to-extend.md) for guidance.
+
+!!! note "Impact on backwards compatibility with DCAT-AP+"
+    Because Chem-DCAT-AP is a closed profile, data that carries properties beyond what is defined here cannot currently be round-tripped through validation against the parent DCAT-AP+ schema either. Additional relations that are valid DCAT-AP+ data will be rejected at the Chem-DCAT-AP layer. This is a known consequence of the closed-world model and will be addressed once LinkML supports per-class open/closed world configuration upstream.
+
+    Progress on the underlying issue is tracked in [issue #85](https://github.com/nfdi-de/dcat-ap-plus/issues/85) and [issue #40](https://github.com/nfdi-de/dcat-ap-plus/issues/40) of the DCAT-AP+ repository.
+
+---
+
+## Technical details
+
+!!! warning "For experts: prefix resolution during conversion"
+
+    When `linkml-convert` encounters a CURIE, it resolves it against the prefix map embedded in the schema (`src/chem_dcat_ap/schema/chem_dcat_ap.yaml`, under `prefixes:`). The prefix map is generated from the [Bioregistry](https://bioregistry.io/) and covers ~2,000 common prefixes.
+
+    If a required prefix is missing, you can supply it at the command line using `--prefix`, or extend the schema locally. See the section on CURIEs above for concrete examples.