Apply specific @metadata to make DFRNT use a different property than "label" for search and display purposes.

1. a string value on a type as part of the @metadata top level section (only on document types). Noted that this value is only used for type-specific searches. For general searches, like global search, that spans types, the schema context value below is used.

   @metadata ᐳ DFRNT ᐳ labelPropertyOverride

2. a string value as part of the schema context @metadata section, which doubles as the 
   global primary label property:

   @metadata ᐳ DFRNT ᐳ defaultLabelProperty

3. an array value as part of the schema context @metadata section, selected in order based on what is available for a specific type. For typeless searches (like global search), the first defaultLabelProperty in the array is used as the global primary label property.

4. If no value is present or applicable, the system uses "label" as the global primary label property if it exists, and falls back to using the instance @id value if no label property is found.

Search with the globally primary "label" property, defaultLabelProperty

If you add no extra @metadata to your schema or types, the system will look for the "label" property on types, based on either inheritance or as defined directly on the property.

The "label" property and @id are both used in global search to find documents in the system, using the PCRE regex syntax (regular expressions). If the "label" property has been redefined according to above, search will work with the selected global primary label property.

The type-specific labelPropertyOverride

Setting the labelPropertyOverride @metadata/DFRNT property to a string helps the system select a specific property of the type to use for filtering and document labels. It will not be used in global search.

Interaction and use together with type and property RDF prefixes

All content in DFRNT is based on knowledge atoms, another name for Resource Description Framework triples, encoded as JSON-LD documents. properties also follow the RDF model and may use prefixes. Prefixes for both @id and properties get defined using the Schema Context Editor.

Prefixes are supported in property labels, such as "rdfs:label", or "skos:prefLabel" so that they can be used instead of the default "@schema:label", which the system defaults to as "label" as the @schema prefix is the global default "@base" by default. To use "rdfs:label", the next two examples show how to accomplish this for a type, and globally respectively, where the global default will be set as an array.

Example schema context for defaultLabelProperty

The default schema context for a graph data product branch is changed by editing the schema context object for the branch and add or modify the DFRNT section of the @metadata section.

The Context Editor is found in the Data Product Browser view above the class hierarchy. The below context assumes a default TerminusDB context for the branch.

{
  "@base": "terminusdb:///data/",
  "@schema": "terminusdb:///schema#",
  "@type": "@context",
  "@metadata": {
    "DFRNT": {
      "defaultLabelProperty": ["rdfs:label", "skos:prefLabel"]
    }
  }
}

Here we have instructed the system to use "rdfs:label" (without the quotes) as the global primary label property for search and for documents types that have or inherits a property "rdfs:label".

For documents that don't have "rdfs:label", we instruct the system to display "skos:prefLabel", but when searching. "skos:prefLabel" results will not be shown, instead documents that lack "rdfs:label" will only match if their @id match the search query.

Example type with labelPropertyOverride

For this example, we assume that the "rdfs:label", and "skos:prefLabel" is only used for most documents. Some document types, including Person, instead use displayName as their primary display name, which should be used for filtering as well. These also have a "rdfs:label" fallback for global search, and includes additional search metadata. The type definition for Person thus looks like below, simplified.

{
  "@type": "Class",
  "@key": {
    "@type": "Random"
  },
  "@metadata": {
      "DFRNT": {
          "labelPropertyOverride": "displayName"
      }
  }
  "@id": "Person",
  "@inherits": [
    "Entity"
  ],
  "@documentation": [
    {
      "@properties": {
        "displayName": {
          "@label": "The person's display name"
        },
        "href": {
          "@label": "Person's homepage"
        },
        "imageUrl": {
          "@label": "Url to image of person"
        }
      }
    }
  ],
  "imageUrl": {
    "@class": "xsd:anyURI",
    "@type": "Optional"
  },
  "href": {
    "@class": "xsd:anyURI",
    "@type": "Optional"
  },
  "displayName": {
    "@class": "xsd:string",
    "@type": "Optional"
  }
}

Conclusion

You can use custom properties to assign document labels for documents in your graph data product. Depending on how you set them up, you can achieve various outcomes for search and document label naming in the systems.

There are some limitations to search functions with custom properties to be aware of and not all combinations are possible to achieve, this is a tradeoff made for search performance purposes to work with enough performance across hosted and local versions of data products..