Creating examples

Examples help developers understand how they can integrate the building block into their applications. Code snippets in specific programming languages, are not only supported, but encouraged.

Each example consists of Markdown content and/or a list of snippets. snippets, in turn, have a language (for highlighting, language tabs in Slate, etc.) and the code itself.

content accepts text in Markdown format. Any relative links or images will be resolved to full URLs when the building block is published.

Instead of the code, a ref with a filename relative to examples.yaml can be provided:

examples:
  - title: My inline example
    content: Example with its code in the examples.yaml file
    snippets:
      - language: json
        code: '{ "a": 1 }'
  - title: My referenced example
    content: Example with its code pulled from a file
    snippets:
      - language: json
        ref: example1.json # in the same directory as examples.yaml

A json-path expression can be combined with ref to extract a specific value from the referenced file instead of using its full contents. Both JSON and YAML files are supported. The first match of the expression is used as the snippet code. If the file cannot be parsed or the expression matches nothing, the snippet is skipped with a warning.

examples:
  - title: My extracted example
    content: Only the "features" array from a GeoJSON file
    snippets:
      - language: json
        ref: example1.json
        json-path: $.features

Please refer to the updated JSON schema for examples.yaml for more information.

The examples.yaml file in my-building-block can be used as a template.

Prefixes

Optionally, you can add a prefixes entry at the top level (alongside examples:) or inside a specific example, with a dictionary of prefix-to-URI mappings, allowing you to omit those prefixes when used in JSON, JSON-LD and Turtle examples, but that will be used when semantically uplifting the snippets:

prefixes:
  # Default prefixes for all examples
  rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns#
  rdfs: http://www.w3.org/2000/01/rdf-schema#
examples:
  - title: Example with prefixes
    prefixes:
      ex: http://example.com/
    snippets:
      - language: turtle
        code: |
          ex:a rdfs:label "A" .

SHACL closures for examples

A snippet can declare its own shacl-closure: a list of Turtle documents (file names, relative to examples.yaml, or URLs) with background RDF data needed for that snippet’s SHACL validation to pass — e.g. a small codelist or class hierarchy that only this example depends on. It is merged with the building block’s own shaclClosures (see SHACL Validation), so you only need it for data that isn’t already part of the block’s general closure graph.

examples:
  - snippets:
      - language: json
        code: '{ "type": "Bird" }'
        shacl-closure:
          - extra-taxonomy.ttl

shacl-closure belongs to the snippet, not the example, since each snippet is validated independently. For a JSON snippet, put it on the JSON snippet itself — the SHACL closure is applied when the JSON is semantically uplifted and validated. If doc-uplift-formats causes a JSON-LD or Turtle twin to be auto-generated for the documentation, that generated snippet is a display-only copy of the already-validated JSON snippet and isn’t independently re-validated, so there’s no need to repeat shacl-closure on it. Only add shacl-closure to a separately authored JSON-LD/Turtle snippet if you write one by hand instead of relying on the auto-generated one.