diff --git a/content/docs/standard/table-schema.mdx b/content/docs/standard/table-schema.mdx index 9d27feb9..423fed38 100644 --- a/content/docs/standard/table-schema.mdx +++ b/content/docs/standard/table-schema.mdx @@ -647,6 +647,27 @@ A constraints descriptor `MUST` be a JSON `object` and `MAY` contain one or more Indicates whether this field cannot be `null`. If required is `false` (the default), then `null` is allowed. See the section on `missingValues` for how, in the physical representation of the data, strings can represent `null` values. +For example, this data file: + +```csv +id,name +1,apple +2, +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string", "constraints": { "required": true } } + ] +} +``` + +Will be invalid because the `name` field is missing a value for the second row. + ### `unique` - **Type**: boolean @@ -654,6 +675,27 @@ Indicates whether this field cannot be `null`. If required is `false` (the defau If `true`, then all values for that field `MUST` be unique within the data file in which it is found. +For example, this data file: + +```csv +id,name +1,apple +2,apple +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string", "constraints": { "unique": true } } + ] +} +``` + +Will be invalid because the `name` field has a duplicate value. + ### `minLength` {#minLength} - **Type**: integer @@ -661,6 +703,27 @@ If `true`, then all values for that field `MUST` be unique within the data file An integer that specifies the minimum length of a value. +For example, this data file: + +```csv +id,name +1,apple +2,orng +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string", "constraints": { "minLength": 5 } } + ] +} +``` + +Will be invalid because the `name` field has a value that is too short. + ### `maxLength` {#maxLength} - **Type**: integer @@ -668,6 +731,27 @@ An integer that specifies the minimum length of a value. An integer that specifies the maximum length of a value. +For example, this data file: + +```csv +id,name +1,apple +2,orange-very-long +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string", "constraints": { "maxLength": 5 } } + ] +} +``` + +Will be invalid because the `name` field has a value that is too long. + ### `minimum` - **Type**: integer, number, date, time, datetime, duration, year, yearmonth @@ -675,6 +759,28 @@ An integer that specifies the maximum length of a value. Specifies a minimum value for a field. 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. The range checking depends on the `type` of the field. E.g. an integer field may have a minimum value of 100; a date field might have a minimum date. If a `minimum` value constraint is specified then the field descriptor `MUST` contain a `type` key. +For example, this data file: + +```csv +id,name,price +1,apple,100 +2,orange,50 +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string" }, + { "name": "price", "type": "integer", "constraints": { "minimum": 75 } } + ] +} +``` + +Will be invalid because the `price` field has a value that is too low. + ### `maximum` - **Type**: integer, number, date, time, datetime, duration, year, yearmonth @@ -682,6 +788,28 @@ Specifies a minimum value for a field. This is different to `minLength` which ch As for `minimum`, but specifies a maximum value for a field. +For example, this data file: + +```csv +id,name,price +1,apple,100 +2,orange,150 +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string" }, + { "name": "price", "type": "integer", "constraints": { "maximum": 125 } } + ] +} +``` + +Will be invalid because the `price` field has a value that is too high. + ### `exclusiveMinimum` {#exclusiveMinimum} - **Type**: integer, number, date, time, datetime, duration, year, yearmonth @@ -689,6 +817,28 @@ As for `minimum`, but specifies a maximum value for a field. As for `minimum`, but for expressing exclusive range. +For example, this data file: + +```csv +id,name,price +1,apple,100 +2,orange,50 +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string" }, + { "name": "price", "type": "integer", "constraints": { "exclusiveMinimum": 100 } } + ] +} +``` + +Will be invalid because the `price` field has a value that is too low. + ### `exclusiveMaximum` {#exclusiveMaximum} - **Type**: integer, number, date, time, datetime, duration, year, yearmonth @@ -696,6 +846,28 @@ As for `minimum`, but for expressing exclusive range. As for `maximum`, but for expressing exclusive range. +For example, this data file: + +```csv +id,name,price +1,apple,100 +2,orange,50 +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string" }, + { "name": "price", "type": "integer", "constraints": { "exclusiveMaximum": 100 } } + ] +} +``` + +Will be invalid because the `price` field has a value that is too high. + ### `jsonSchema` {#jsonSchema} - **Type**: object @@ -703,6 +875,39 @@ As for `maximum`, but for expressing exclusive range. A valid JSON Schema object to validate field values. If a field value conforms to the provided JSON Schema then this field value is valid. +For example, this data file: + +```csv +id,name,price +1,apple,{"value": 100} +2,orange,{"value": "bad"} +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string" }, + { + "name": "price", + "type": "object", + "constraints": { + "jsonSchema": { + "type": "object", + "properties": { + "value": { "type": "integer" } + } + } + } + } + ] +} +``` + +Will be invalid because the `price` field has a value that is not an integer. + ### `pattern` - **Type**: string @@ -710,6 +915,27 @@ A valid JSON Schema object to validate field values. If a field value conforms t A regular expression that can be used to test field values. If the regular expression matches then the value is valid. The values of this field `MUST` conform to the standard [XML Schema regular expression syntax](http://www.w3.org/TR/xmlschema-2/#regexs). +For example, this data file: + +```csv +id,name +1,apple +2,orng +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string", "constraints": { "pattern": "^a.*$" } } + ] +} +``` + +Will be invalid because the `name` field has a value that does not match the pattern. + ### `enum` - **Type**: array @@ -717,6 +943,27 @@ A regular expression that can be used to test field values. If the regular expre The value of the field `MUST` exactly match one of the values in the `enum` array. +For example, this data file: + +```csv +id,name +1,apple +2,orange +``` + +With this schema definition: + +```json +{ + "fields": [ + { "name": "id", "type": "integer" }, + { "name": "name", "type": "string", "constraints": { "enum": ["apple"] } } + ] +} +``` + +Will be invalid because the `name` field has a value that is not in the `enum` array. + :::note[Implementation Note] - Implementations `SHOULD` report an error if an attempt is made to evaluate a value against an unsupported constraint. @@ -735,3 +982,7 @@ Table Schema draws content and/or inspiration from, among others, the following - [DSPL](https://developers.google.com/public-data/docs/schema/dspl18) - [HTML5 Forms](http://www.whatwg.org/specs/web-apps/current-work/#attr-input-typ) - [Elasticsearch](http://www.elasticsearch.org/guide/reference/mapping/) + +``` + +```