Overview

This document serves as a guide for using GRCSchema.org data and designing new or amended schemas. It contains information on schema design principles, writing and naming conventions, and usability conventions for consuming schema. It does not currently address modeling design patterns.

GRCSchema.org terms

The GRCSchema.org data model has three kinds of GRCSchema.org terms: types, properties, and enumerated values. All GRCSchema.org data is represented in a graph structure in which entities are related to each other by named properties.

Type

• TitleCase for case format (all words capitalized, all one string).
• E.g. CoreMetaData.

Types have associated properties.

E.g. CoreMetaData has the property liveStatus.

• Types also take their associated properties from their parent types, i.e., supertypes.
• When a type is a child of another type, its name uses the lowerCamelCase for format (see below).

Types within types are treated as Objects

E.g., Created contains the Object Person instead of the Type Person

• The reason for this is that @context only appears at the root of the JSON body in the response, not inside of every thing.
• @type is to define the object structure that relates back to the Thing.

Objects

• Objects as property values must also have a documented type (at Thing).
  • E.g., ‘Organization’ is defined as a Thing. However, ‘organization’ when used as an object references the @type ‘Organization’.

{
    "organization" : 
    {
        "@id" : "URL | The full unique link to the item so it's traversable by that property.",
        "@type" : "Organization",
        "elementId" : "String | A unique and persistent identifier for the record within the system's data set.",
        "name" : "String | The name of the item or record."
    }
}

Property

• Property names must use lowerCamelCase for format (first word lowercase, subsequent words capitalized, all one string).
  • E.g. liveStatus.
• Properties are always entered in the singular format.
  • E.g. name and not names

Properties may be used on more than one type.

• E.g. the property liveStatus will be used on most every Type element found within GRCSchema.org.

Arrays

• An array of properties is named as the pluralized version of the property.
  • E.g. an array of name is presented as names.
• Each array will contain the property it references.
  • E.g. “names” contains the property “name” as shown below.

{
    "names" : 
    [
        {
            "name" : "String | The name of the item or record."
        }
    ]
}

• Always presume that arrays are unordered. Any ordering or hierarchical information must be provided as a property of the array.

Enumerations

More to come…

Naming conventions

• Thing, object, and property names should use Singular naming only, even if the semantics call for a plural.
  • E.g. parent and not parents, even though for each type, there will always be multiple values for the property parent.
• Prepositions will come after the type or property name.
  • E.g. reservationFor.
• Abbreviations: When creating new types and properties, spell out abbreviations unless the result is painfully verbose.
• Spelling: US spellings must be used.
  • E.g. color and not colour.