Skip to content
Knowboard

Data Shapes

As your workspace grows it can help to describe what fields and relationships exist for different types of data.

Knowboard recognizes the Shapes Constraint Language (SHACL) to describe your data. Public entities like schema.org may provide their own shapes, but we’ll build up a simple representation of the shapes to describe just the fields that we use for this example.

So far we’ve used YAML-LD for consistency, but since most of the documentation for SHACL uses the Turtle format, we’ll switch to that for this section.

We can describe the “shape” of a Book, and list properties like the “name” that exist for that class:

shapes.yamlld
"@context":
  kbex: "tag:me@example.com,2026:my-workspace/"
  sh: "http://www.w3.org/ns/shacl#"
  schema: "http://schema.org/"


"@graph":
  - "@id": kbex:BookShape
    "@type": sh:NodeShape
    sh:targetClass: {"@id": schema:Book}
    sh:property:
      - sh:path: {"@id": schema:name}

In one of your book documents, try adding a blank line, and activate your editor’s auto-complete. You should see “name” pop up as a suggested field:

---
"@context":
    "@vocab": "http://schema.org/"
    "kbex": "tag:me@example.com,2026:my-workspace/"
"@type": Book
<try to auto-complete on this line>
---

Adding relationships

Section titled “Adding relationships”

Next we can add a similar description for the author’s shape as a “Person” with a “name”. In the “Book” shape, we can note that the “author” property should refer to a “Person”.

shapes.yamlld
"@context":
  kbex: "tag:me@example.com,2026:my-workspace/"
  sh: "http://www.w3.org/ns/shacl#"
  schema: "http://schema.org/"


"@graph":
  - "@id": kbex:BookShape
    "@type": sh:NodeShape
    sh:targetClass: {"@id": schema:Book}
    sh:property:
      - sh:path: {"@id": schema:name}
      - sh:path: {"@id": schema:author}
        sh:class: {"@id": schema:Person}


  - "@id": kbex:AuthorShape
    "@type": sh:NodeShape
    sh:targetClass: {"@id": schema:Person}
    sh:property:
      - sh:path: {"@id": schema:name}

Now auto-complete inside a “Book” document should also show the “author” as a suggested property name, and completions for the value should show the people we described in authors.yamlld.

Better previews

Section titled “Better previews”

Knowboard can also use the shapes to give more informative previews of your data. By adding “property roles” you can indicate which properties are most important to display.

For this, we use DASH.

By designating one property in the shape as the “LabelRole”, this will be displayed as the title for that type. Additional properties can be designated with “KeyInfoRole” to add them to the summary with a label.

shapes.yamlld
"@context":
  kbex: "tag:me@example.com,2026:my-workspace/"
  sh: "http://www.w3.org/ns/shacl#"
  schema: "http://schema.org/"
  dash: "http://datashapes.org/dash#"


"@graph":
  - "@id": kbex:BookShape
    "@type": sh:NodeShape
    sh:targetClass: {"@id": schema:Book}
    sh:property:
      - sh:path: {"@id": schema:name}
        dash:propertyRole: {"@id": dash:LabelRole}
      - sh:path: {"@id": schema:author}
        dash:propertyRole: {"@id": dash:KeyInfoRole}
        sh:class: {"@id": schema:Person}


  - "@id": kbex:AuthorShape
    "@type": sh:NodeShape
    sh:targetClass: {"@id": schema:Person}
    sh:property:
      - sh:path: {"@id": schema:name}
        dash:propertyRole: {"@id": dash:LabelRole}
      - sh:path: {"@id": schema:birthDate}
        sh:name: "Born"
        dash:propertyRole: {"@id": dash:KeyInfoRole}
authors.yamlld
"@context":
  "@base": "tag:me@example.com,2026:my-workspace/authors/"
  schema: "http://schema.org/"
  xsd: "http://www.w3.org/2001/XMLSchema#"


"@graph":
  - "@id": f-scott-fitzgerald
    "@type": schema:Person
    schema:name: F. Scott Fitzgerald
    schema:birthDate:
      "@value": 1896-09-24
      "@type": xsd:date


  - "@id": jane-austen
    "@type": schema:Person
    schema:name: Jane Austen
    schema:birthDate:
      "@value": 1775-12-16
      "@type": xsd:date

Now, hovering over an author should show a clearer description of that person:

code hover for "jane austin" showing name and birth date