Table Schema
A simple format to declare a schema for tabular data.

Authors Paul Walsh
Rufus Pollock
Version 1.0.0-rc.1
Last Updated 30 January 2017
Created 12 November 2012

Abstract

Table Schema is a simple, language and implementation agnostic, way to declare a schema for tabular data. The Table Schema specification has been designed to be expressible in JSON.

Goals

Table Schema shares the design philosophy of all Frictionless Data Specifications, being:

  • Requirements that are driven by simplicity
  • Extensibility and customisation by design
  • Metadata that is human-editable and machine-usable
  • Reuse of existing standard formats for data
  • Language-, technology- and infrastructure-agnostic

Changelog

See the Changelog for information.

Language

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

Specification

Table Schema is a simple language- and implementation-agnostic way to declare a schema for tabular data. Table Schema is well suited for use cases around handling and validating tabular data in text formats such as CSV, but its utility extends well beyond this core usage, towards a range of application a where data benefits from a portable schema format.

In its simplest form, Table Schema is an object with a fields property as an array, and each item in the array is a field descriptor, with information on the expected type for data in each field. In this basis, Table Schema also supports declaring more complex shapes for data via format and constraints options per field, as well as more advanced data structures with handling of primaryKey and foreignKeys constructs.

While field descriptors can support complex types via type, format and constraints, the only required property for a field is name, and the absence of the additional modifiers indicates that the field is a string of the default format (meaning, any format), and values are not required (constraints.required == false).

As a foreign key often needs to be able to reference other data resources, the referenced resources need to be in a specific structure in order to work. Therefore, foreign keys only work across valid Tabular Data Resource objects. The special case of reference.resource as an empty string is a self-reference, for foreign keys to self.

Table Schema is heavily based on similar specifications and implementations, in particular XML Schema, GoogleBigQuery, JSON Schema, DSPL, HTML5 Forms, and Elasticsearch.

See below for examples, and a full description of the properties found on Table Schema.

Examples

A minimal Table Schema looks as follows.

{
  "fields": [
    {
      "name": "code",
      "type": "string"
    },
    {
      "name": "parent",
      "type": "string"
    }
  ]
}

A slightly expanded Table Schema with a primary key and a foreign key looks as follows.

{
  "fields": [
    {
      "name": "code",
      "type": "string",
      "constraints": {
        "required": true
      }
    },
    {
      "name": "parent",
      "type": "string",
      "constraints": {
        "required": true
      }
    }
  ],
  "primaryKey": [
    "code",
    "parent"
  ],
  "foreignKeys": [
    {
      "fields": [
        "parent"
      ],
      "reference": {
        "resource": "",
        "fields": [
          "code"
        ]
      }
    }
  ]
}

A complex Table Schema using many features of the specification looks as follows.

{
  "fields": [
    {
      "name": "code",
      "type": "string",
      "constraints": {
        "required": true,
        "minLength": 4,
        "maxLength": 4
      }
    },
    {
      "name": "parent",
      "type": "string",
      "constraints": {
        "required": true,
        "minLength": 4,
        "maxLength": 4
      }
    },
    {
      "name": "title",
      "type": "string",
      "constraints": {
        "required": true
      }
    },
    {
      "name": "description",
      "type": "string"
    },
    {
      "name": "contact",
      "type": "string",
      "format": "email",
      "constraints": {
        "unique": true
      }
    },
    {
      "name": "employees",
      "type": "integer",
      "constraints": {
        "required": true
      }
    },
    {
      "name": "rating",
      "type": "number"
    }
  ],
  "primaryKey": [
    "code",
    "parent"
  ],
  "foreignKeys": {
    "fields": [
      "parent"
    ],
    "reference": {
      "resource": "",
      "fields": [
        "code"
      ]
    }
  },
  "missingValues": [
    "", "-", "None"
  ]
}

Descriptor

A valid Table Schema descriptor is an object conforming with the formal reference outlined in Properties, and the following more general requirements.

Form

The descriptor MUST be valid JSON, as described in RFC 4627, and SHOULD be in one of the following forms:

  1. A file named tableschema.json.
  2. An object, either on its own or nested in another data structure.

A JSON Schema to validate Table Schema descriptors is available here.

Media type

The media type for Table Schema descriptors MUST be application/vnd.tableschema+json. This media type is registered with IANA).

URIs

Several properties are defined as URI-formatted strings, which are to be considered as a subset of the formal URI specification described in RFC 3986. The additional constraints imposed are as follows:

  1. The only supported schemes are http and https. Absence of a scheme indicates either a POSIX path or a JSON Pointer (see below).
  2. URLs, indicated by http or https, MUST be fully qualified.
  3. POSIX paths are supported for referencing local files, with the security restraint that they MUST be relative siblings or children of the descriptor. Absolute paths (/) and relative parent paths (../) MUST NOT be used, and implementations SHOULD NOT support these path types.
  4. JSON Pointers are supported as a general referencing mechanism to other properties in the same descriptor, and therefore MUST start with the pound symbol (#).

Properties

This section presents a complete description of required and optional properties for a Table Schema descriptor.

Adherence to the specification does not imply that additional, non-specified properties cannot be used: a descriptor MAY include any number of properties in additional to those described as required and optional properties.

Required properties

A Table Schema descriptor MUST include the following properties.

fields

An array of Table Schema Field objects.

Examples
{
  "fields": [
    {
      "name": "my-field-name"
    }
  ]
}
{
  "fields": [
    {
      "name": "my-field-name",
      "type": "number"
    },
    {
      "name": "my-field-name-2",
      "type": "string",
      "format": "email"
    }
  ]
}
Options

There are several options for Table Schema Field objects.

String Field

The field contains strings, that is, sequences of characters.

Examples
{
  "name": "name",
  "type": "string"
}
{
  "name": "name",
  "type": "string",
  "format": "email"
}
{
  "name": "name",
  "type": "string",
  "constraints": {
    "minLength": 3,
    "maxLength": 35
  }
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of string.

format

The format keyword options for string are default, email, uri, binary, and uuid.

The following format options are supported:

  • default: any valid string.
  • email: A valid email address.
  • uri: A valid URI.
  • binary: A base64 encoded string representing binary data.
  • uuid: A string that is a uuid.

constraints

The following constraints are supported for string fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

pattern

A regular expression pattern to test each value of the property against, where a truthy response indicates validity.

Regular expressions SHOULD conform to the XML Schema regular expression syntax.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minLength

An integer that specifies the minimum length of a value.

maxLength

An integer that specifies the maximum length of a value.

rdfType

The RDF type for this field.

Number Field

The field contains numbers of any kind including decimals.

The lexical formatting follows that of decimal in XMLSchema: a non-empty finite-length sequence of decimal digits separated by a period as a decimal indicator. An optional leading sign is allowed. If the sign is omitted, '+' is assumed. Leading and trailing zeroes are optional. If the fractional part is zero, the period and following zero(es) can be omitted. For example: '-1.23', '12678967.543233', '+100000.00', '210'.

The following special string values are permitted (case does not need to be respected):

  • NaN: not a number
  • INF: positive infinity
  • -INF: negative infinity

A number MAY also have a trailing:

  • exponent: this MUST consist of an E followed by an optional + or - sign followed by one or more decimal digits (0-9)
  • percentage: the percentage sign: %. In conversion percentages should be divided by 100.

If both exponent and percentages are present the percentage MUST follow the exponent e.g. '53E10%' (equals 5.3).

Examples
{
  "name": "field-name",
  "type": "number"
}
{
  "name": "field-name",
  "type": "number",
  "constraints": {
    "enum": [ "1.00", "1.50", "2.00" ]
  }
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of number.

format

There are no format keyword options for number: only default is allowed.

decimalChar

A string whose value is used to represent a decimal point within the number. The default value is ..

groupChar

A string whose value is used to group digits within the number. The default value is null. A common value is , e.g. '100,000'.

currency

A number that may include additional currency symbols.

constraints

The following constraints are supported for number fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

pattern

A regular expression pattern to test each value of the property against, where a truthy response indicates validity.

Regular expressions SHOULD conform to the XML Schema regular expression syntax.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minimum

A minimum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to minLength, which checks the number of items in the value. A minimum value constraint checks whether a field value is greater than or equal to the specified value.

maximum

A maximum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to maxLength, which checks the number of items in the value. A maximum value constraint checks whether a field value is smaller than or equal to the specified value.

rdfType

The RDF type for this field.

Integer Field

The field contains integers - that is whole numbers.

Integer values are indicated in the standard way for any valid integer.

Examples
{
  "name": "age",
  "type": "integer",
  "constraints": {
    "unique": true,
    "minimum": 100,
    "maximum": 9999
  }
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of integer.

format

There are no format keyword options for integer: only default is allowed.

constraints

The following constraints are supported for integer fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

pattern

A regular expression pattern to test each value of the property against, where a truthy response indicates validity.

Regular expressions SHOULD conform to the XML Schema regular expression syntax.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minimum

A minimum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to minLength, which checks the number of items in the value. A minimum value constraint checks whether a field value is greater than or equal to the specified value.

maximum

A maximum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to maxLength, which checks the number of items in the value. A maximum value constraint checks whether a field value is smaller than or equal to the specified value.

rdfType

The RDF type for this field.

Date Field

The field contains temporal date values.

Examples
{
  "name": "date_of_birth",
  "type": "date"
}
{
  "name": "date_of_birth",
  "type": "date",
  "constraints": {
    "minimum": "01-01-1900"
  }
}
{
  "name": "date_of_birth",
  "type": "date",
  "format": "MM-DD-YYYY"
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of date.

format

The format keyword options for date are default, any, and {PATTERN}.

The following format options are supported:

  • default: An ISO8601 format string of YYYY-MM-DD.
  • any: Any parsable representation of a date. The implementing library can attempt to parse the datetime via a range of strategies.
  • {PATTERN}: The value can be parsed according to {PATTERN}, which MUST follow the date formatting syntax of C / Python strftime.

constraints

The following constraints are supported for date fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minimum

A minimum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to minLength, which checks the number of items in the value. A minimum value constraint checks whether a field value is greater than or equal to the specified value.

maximum

A maximum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to maxLength, which checks the number of items in the value. A maximum value constraint checks whether a field value is smaller than or equal to the specified value.

rdfType

The RDF type for this field.

Time Field

The field contains temporal time values.

Examples
{
  "name": "appointment_start",
  "type": "time"
}
{
  "name": "appointment_start",
  "type": "time",
  "format": "any"
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of time.

format

The format keyword options for time are default, any, and {PATTERN}.

The following format options are supported:

  • default: An ISO8601 format string for time.
  • any: Any parsable representation of a date. The implementing library can attempt to parse the datetime via a range of strategies.
  • {PATTERN}: The value can be parsed according to {PATTERN}, which MUST follow the date formatting syntax of C / Python strftime.

constraints

The following constraints are supported for time fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minimum

A minimum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to minLength, which checks the number of items in the value. A minimum value constraint checks whether a field value is greater than or equal to the specified value.

maximum

A maximum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to maxLength, which checks the number of items in the value. A maximum value constraint checks whether a field value is smaller than or equal to the specified value.

rdfType

The RDF type for this field.

Date Time Field

The field contains temporal datetime values.

Examples
{
  "name": "timestamp",
  "type": "datetime"
}
{
  "name": "timestamp",
  "type": "datetime",
  "format": "default"
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of datetime.

format

The format keyword options for datetime are default, any, and {PATTERN}.

The following format options are supported:

  • default: An ISO8601 format string for datetime.
  • any: Any parsable representation of a date. The implementing library can attempt to parse the datetime via a range of strategies.
  • {PATTERN}: The value can be parsed according to {PATTERN}, which MUST follow the date formatting syntax of C / Python strftime.

constraints

The following constraints are supported for datetime fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minimum

A minimum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to minLength, which checks the number of items in the value. A minimum value constraint checks whether a field value is greater than or equal to the specified value.

maximum

A maximum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to maxLength, which checks the number of items in the value. A maximum value constraint checks whether a field value is smaller than or equal to the specified value.

rdfType

The RDF type for this field.

Year Field

A calendar year, being an integer with 4 digits. Equivalent to gYear in XML Schema

Examples
{
  "name": "year",
  "type": "year"
}
{
  "name": "year",
  "type": "year",
  "constraints": {
    "minimum": 1970,
    "maximum": 2003
  }
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of year.

format

There are no format keyword options for year: only default is allowed.

constraints

The following constraints are supported for year fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minimum

A minimum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to minLength, which checks the number of items in the value. A minimum value constraint checks whether a field value is greater than or equal to the specified value.

maximum

A maximum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to maxLength, which checks the number of items in the value. A maximum value constraint checks whether a field value is smaller than or equal to the specified value.

rdfType

The RDF type for this field.

Year Month Field

A calendar year month, being an integer with 1 or 2 digits. Equivalent to gYearMonth in XML Schema

Examples
{
  "name": "month",
  "type": "yearmonth"
}
{
  "name": "month",
  "type": "yearmonth",
  "constraints": {
    "minimum": 1,
    "maximum": 6
  }
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of yearmonth.

format

There are no format keyword options for yearmonth: only default is allowed.

constraints

The following constraints are supported for yearmonth fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

pattern

A regular expression pattern to test each value of the property against, where a truthy response indicates validity.

Regular expressions SHOULD conform to the XML Schema regular expression syntax.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minimum

A minimum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to minLength, which checks the number of items in the value. A minimum value constraint checks whether a field value is greater than or equal to the specified value.

maximum

A maximum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to maxLength, which checks the number of items in the value. A maximum value constraint checks whether a field value is smaller than or equal to the specified value.

rdfType

The RDF type for this field.

Boolean Field

The field contains boolean (true/false) data.

Boolean values can be indicated with the following strings (case-insensitive, so, for example, 'Y' and 'y' are both acceptable):

  • true: 'yes', 'y', 'true', 't', '1'
  • false: 'no', 'n', 'false', 'f', '0'
Examples
{
  "name": "registered",
  "type": "boolean"
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of boolean.

constraints

The following constraints are supported for boolean fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

rdfType

The RDF type for this field.

Object Field

The field contains data which can be parsed as a valid JSON object.

Examples
{
  "name": "extra"
  "type": "object"
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of object.

format

There are no format keyword options for object: only default is allowed.

constraints

The following constraints apply for object fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minLength

An integer that specifies the minimum length of a value.

maxLength

An integer that specifies the maximum length of a value.

rdfType

The RDF type for this field.

GeoPoint Field

The field contains data describing a geographic point.

Examples
{
  "name": "post_office",
  "type": "geopoint"
}
{
  "name": "post_office",
  "type": "geopoint",
  "format": "array"
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of geopoint.

format

The format keyword options for geopoint are default,array, and object.

The following format options are supported:

  • default: A string of the pattern 'lon, lat', where lon is the longitude and lat is the latitude.
  • array: An array of exactly two items, where each item is either a number, or a string parsable as a number, and the first item is lon and the second item is lat.
  • object: A JSON object with exactly two keys, lat and lon
Notes
  • Implementations MUST strip all white space in the default format of lon, lat.

constraints

The following constraints are supported for geopoint fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

rdfType

The RDF type for this field.

GeoJSON Field

The field contains a JSON object according to GeoJSON or TopoJSON

Examples
{
  "name": "city_limits",
  "type": "geojson"
}
{
  "name": "city_limits",
  "type": "geojson",
  "format": "topojson"
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of geojson.

format

The format keyword options for geojson are default and topojson.

The following format options are supported:

constraints

The following constraints are supported for geojson fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minLength

An integer that specifies the minimum length of a value.

maxLength

An integer that specifies the maximum length of a value.

rdfType

The RDF type for this field.

Array Field

The field contains data which can be parsed as a valid JSON array.

Examples
{
  "name": "options"
  "type": "array"
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of array.

format

There are no format keyword options for array: only default is allowed.

constraints

The following constraints apply for array fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minLength

An integer that specifies the minimum length of a value.

maxLength

An integer that specifies the maximum length of a value.

rdfType

The RDF type for this field.

Duration Field

The field contains a duration of time.

The lexical representation for duration is the ISO 8601 extended format PnYnMnDTnHnMnS, where nY represents the number of years, nM the number of months, nD the number of days, 'T' is the date/time separator, nH the number of hours, nM the number of minutes and nS the number of seconds. The number of seconds can include decimal digits to arbitrary precision. Date and time elements including their designator may be omitted if their value is zero, and lower order elements may also be omitted for reduced precision. Here we follow the definition of XML Schema duration datatype directly and that definition is implicitly inlined here.

Examples
{
  "name": "period"
  "type": "duration"
}
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of duration.

format

There are no format keyword options for duration: only default is allowed.

constraints

The following constraints are supported for duration fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

minimum

A minimum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to minLength, which checks the number of items in the value. A minimum value constraint checks whether a field value is greater than or equal to the specified value.

maximum

A maximum value for the property, context specific for the property type, and conforming with the format for the property.

This is different to maxLength, which checks the number of items in the value. A maximum value constraint checks whether a field value is smaller than or equal to the specified value.

rdfType

The RDF type for this field.

Any Field

Any value is accepted, including values that are not captured by the type/format/constraint requirements of the specification.

Examples
{
  "name": "notes",
  "type": "any"
Properties

name

An identifier string. Lower case characters with ., _, - and / are allowed.

This is ideally a url-usable and human-readable name. Name SHOULD be invariant, meaning it SHOULD NOT change when its parent descriptor is updated.

title

A human-readable title.

description

A text description. Markdown is encouraged.

type

The type keyword, which MUST be a value of any.

constraints

The following constraints apply to any fields.

Properties

required

Indicates whether a property must have a value for each instance.

An empty string is considered to be a missing value.

unique

When true, each value for the property MUST be unique.

enum

An array of values, where the property value MUST match any. Each enum item MUST comply with the type and format of the property.

rdfType

The RDF type for this field.

Optional properties

A Table Schema descriptor SHOULD include the following properties.

primaryKey

A primary key is an array of field names, whose values MUST uniquely identify each row in the table.

Each string in the primaryKey array MUST be unique, and MUST match a field name in the associated table. It is acceptable to have an array with a single value, indicating that the value of a single field is the primary key.

Examples
{
  "primaryKey": [
    "name"
  ]
}
{
  "primaryKey": [
    "first_name",
    "last_name"
  ]
}
Items

Each item in the array is a string. The property is required, and other defined properties are optional.

foreignKeys

Examples
{
  "foreignKeys": [
    {
      "fields": "state",
      "reference": {
        "resource": "the-resource",
        "fields": "state_id"
      }
    }
  ]
}
{
  "foreignKeys": [
    {
      "fields": "state",
      "reference": {
        "resource": "",
        "fields": "id"
      }
    }
  ]
}
Items

Each item in the array is a Table Schema Foreign Key object. The fields, reference properties are required, and other defined properties are optional.

fields

Fields that make up the primary key.

Items

Each item in the array is a string. The property is required, and other defined properties are optional.

reference

missingValues

Values that when encountered in the source, should be considered as null, 'not present', or 'blank' values.

Many datasets arrive with missing data values, either because a value was not collected or it never existed. Missing values may be indicated simply by the value being empty in other cases a special value may have been used e.g. -, NaN, 0, -9999 etc. The missingValues property provides a way to indicate that these values should be interpreted as equivalent to null.

missingValues are strings rather than being the data type of the particular field. This allows for comparison prior to casting and for fields to have missing value which are not of their type, for example a number field to have missing values indicated by -.

The default value of missingValue for a non-string type field is the empty string ''. For string type fields there is no default for missingValue (for string fields the empty string '' is a valid value and need not indicate null).

Examples
{
  "missingValues": [
    "-",
    "NaN",
    ""
  ]
}
Items

Each item in the array is a string. The property is required, and other defined properties are optional.

Implementations

The following implementations are available for table-schema:

See the implementation page for further information on writing an implementation of a Frictionless Data specification.