Overview

This document is the guide for using GRCSchema.org data and for designing new or amended schemas. It covers schema design principles, writing and naming conventions, and usability conventions for consuming schemas. It does not currently address modeling design patterns.

The conventions exist for one reason: structures contributed by many different organizations have to stay legible to every consumer who didn't write them. Follow the conventions and your schema reads like every other schema on the site. That's the point.

GRCSchema.org terms

The GRCSchema.org data model has three kinds of 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.

Types

• Types use TitleCase (all words capitalized, all one string). E.g. CoreMetaData.
• Types have associated properties. E.g. CoreMetaData has the property live.
• Types inherit the properties of their parent types (supertypes).
• When a type appears as the value of a property, the property name uses lowerCamelCase (see below).

Types within types are treated as Objects

E.g., Created contains the Object Person rather than repeating the full Type Person.

• @context appears only at the root of the JSON body in the response, not inside every nested thing.
• @type declares the object structure, which relates the object back to its Thing definition.

Objects

Objects used as property values must also have a documented type (at Thing level). E.g., Organization is defined as a Thing. When used as an object value, organization 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."
	}
}

Properties

• Property names use lowerCamelCase (first word lowercase, subsequent words capitalized, all one string). E.g. supersededBy.
• Scalar and object properties are always named in the singular. E.g. name, not names. Likewise parent, not parents.
• Properties may be used on more than one type. E.g. coreMetaData appears on nearly every Thing on GRCSchema.org.

Arrays

Arrays are the one deliberate exception to the singular rule:

• An array property is named as the pluralized version of the property it contains. E.g. an array of name values is names.
• Each item in the array carries the singular property it references:

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

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

So the rule in one line: singular for scalars and objects, plural only for the arrays that contain them.

Enumerations

Enumerated values are controlled string lists attached to a specific property. Conventions:

• Enumerated values are written in Title Case. E.g. the status property of CoreMetaData takes values like Released, In Review, and On Hold (ten in all, documented on the property).
• The full value list is documented on the property that carries it, and the list is closed: if a value isn't documented, it isn't valid.
• Adding a value to an enumeration is a schema change and goes through the same proposal process as any other change (see How we work).

Naming conventions

• Prepositions 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. E.g. color, not colour.