From 1b342ad9400d299033f3069887d42b2f80eff8ec Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 4 Jan 2024 13:05:37 +0100 Subject: [PATCH 1/4] Added format fields --- CHANGELOG.md | 6 ++ README.md | 83 +++++++++++++++++++--------- datacontract.schema.json | 116 +++++++++++++++++++++++++++++++++++++-- 3 files changed, 174 insertions(+), 31 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 856f1d7..d4ec1e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 Please note, while the major version is zero (0.y.z), Anything MAY change at any time. The public API SHOULD NOT be considered stable. +## [0.9.2] - 2024-01-04 + +### Added + +- Format and validation attributes to fields in models and definitions + ## [0.9.1] - 2023-11-19 ### Added diff --git a/README.md b/README.md index d44a737..6c3dbab 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ Data usage agreements have a defined lifecycle, start/end date, and help the dat Version --- -0.9.1 ([Changelog](CHANGELOG.md)) +0.9.2 ([Changelog](CHANGELOG.md)) Example --- @@ -37,7 +37,7 @@ Example [![Open in Data Contract Studio](https://img.shields.io/badge/open%20in-Data%20Contract%20Studio-blue)](https://studio.datacontract.com/) ```yaml -dataContractSpecification: 0.9.1 +dataContractSpecification: 0.9.2 id: urn:datacontract:checkout:orders-latest-npii info: title: Orders Latest NPII @@ -70,18 +70,32 @@ models: order_id: $ref: '#/definitions/order_id' order_timestamp: - type: timestamp description: The business timestamp in UTC when the order was successfully registered in the source system and the payment was successful. + type: timestamp + required: true order_total: - type: long description: Total amount the smallest monetary unit (e.g., cents). + type: long + required: true + customer_id: + description: Unique identifier for the customer. + type: text + minLength: 10 + maxLength: 20 + customer_email_address: + description: The email address, as entered by the customer. The email address was not verified. + type: text + format: email + required: true line_items: description: A single article that is part of an order. type: table fields: lines_item_id: - type: string + type: text description: Primary key of the lines_item_id table + required: true + unique: true order_id: $ref: '#/definitions/order_id' sku: @@ -92,7 +106,8 @@ definitions: domain: checkout name: order_id title: Order ID - type: string + type: text + format: uuid description: An internal ID that identifies an order in the online shop. example: 243c25e5-a081-43a9-aeab-6d5d5b6cb5e2 pii: true @@ -101,8 +116,9 @@ definitions: domain: inventory name: sku title: Stock Keeping Unit - type: string - example: AC1212ME1 + type: text + pattern: ^[A-Za-z0-9]{8,14}$ + example: 96385074 description: | A Stock Keeping Unit (SKU) is an internal unique identifier for an article. It is typically associated with an article's barcode, such as the EAN/GTIN. @@ -319,14 +335,21 @@ The name of the data model (table name) is defined by the key that refers to thi The Field Objects describes one field (column, property, nested field) of a data model. -| Field | Type | Description | -|----------------|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| type | [Data Type](#data-types) | The logical data type of the field. | -| description | `string` | An optional string describing the semantic of the data in this field. | -| pii | `boolean` | An indication, if this field contains Personal Identifiable Information (PII). | -| classification | `string` | The data class defining the sensitivity level for this field, according to the organization's classification scheme. Examples may be: `sensitive`, `restricted`, `internal`, `public`. | -| tags | Array of `string` | Custom metadata to provide additional context. | -| $ref | `string` | A reference URI to a definition in the specification, internally or externally. Properties will be inherited from the definition. | +| Field | Type | Description | +|----------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| description | `string` | An optional string describing the semantic of the data in this field. | +| type | [Data Type](#data-types) | The logical data type of the field. | +| required | `boolean` | An indication, if this field must contain a value and may not be null. Default: `false` | +| unique | `boolean` | An indication, if the value must be unique within the model. Default: `false` | +| minLength | `number` | A value must greater than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| maxLength | `number` | A value must less than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| format | `string` | `email`: A value must be complaint to [RFC 5321, section 4.1.2](https://www.rfc-editor.org/info/rfc5321).
`uri`: A value must be complaint to [RFC 3986](https://www.rfc-editor.org/info/rfc3986).
`uuid`: A value must be complaint to [RFC 4122](https://www.rfc-editor.org/info/rfc4122). Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| pattern | `string` | A value must be valid according to the [ECMA-262](https://262.ecma-international.org/5.1/) regular expression dialect. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| example | `string` | An example value. | +| pii | `boolean` | An indication, if this field contains Personal Identifiable Information (PII). | +| classification | `string` | The data class defining the sensitivity level for this field, according to the organization's classification scheme. Examples may be: `sensitive`, `restricted`, `internal`, `public`. | +| tags | Array of `string` | Custom metadata to provide additional context. | +| $ref | `string` | A reference URI to a definition in the specification, internally or externally. Properties will be inherited from the definition. | ### Definition Object @@ -335,17 +358,23 @@ The Definition Object includes a clear and concise explanations of syntax, seman It serves as a reference for a common understanding of terminology, ensure consistent usage and to identify join-able fields. Models fields can refer to definitions using the `$ref` field to link to existing definitions and avoid duplicate documentations. -| Field | Type | Description | -|----------------|--------------------------|----------------------------------------------------------------------------------------------------------------------| -| domain | `string` | The domain in which this definition is valid. Default: `global`. | -| name | `string` | The technical name of this definition. | -| title | `string` | The business name of this definition. | -| type | [Data Type](#data-types) | The logical data type | -| description | `string` | Clear and concise explanations related to the domain | -| example | `string` | An example value. | -| pii | `boolean` | An indication, if this field contains Personal Identifiable Information (PII). | -| classification | `string` | The data class defining the sensitivity level for this field, according to the organization's classification scheme. | -| tags | Array of `string` | Custom metadata to provide additional context. | +| Field | Type | Description | +|----------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| domain | `string` | The domain in which this definition is valid. Default: `global`. | +| name | `string` | The technical name of this definition. | +| title | `string` | The business name of this definition. | +| description | `string` | Clear and concise explanations related to the domain | +| type | [Data Type](#data-types) | The logical data type | +| required | `boolean` | An indication, if this field must contain a value and may not be null. Default: `false` | +| unique | `boolean` | An indication, if the value must be unique within the model. Default: `false` | +| minLength | `number` | A value must greater than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| maxLength | `number` | A value must less than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| format | `string` | `email`: A value must be complaint to [RFC 5321, section 4.1.2](https://www.rfc-editor.org/info/rfc5321).
`uri`: A value must be complaint to [RFC 3986](https://www.rfc-editor.org/info/rfc3986).
`uuid`: A value must be complaint to [RFC 4122](https://www.rfc-editor.org/info/rfc4122). Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| pattern | `string` | A value must be valid according to the [ECMA-262](https://262.ecma-international.org/5.1/) regular expression dialect. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| example | `string` | An example value. | +| pii | `boolean` | An indication, if this field contains Personal Identifiable Information (PII). | +| classification | `string` | The data class defining the sensitivity level for this field, according to the organization's classification scheme. | +| tags | Array of `string` | Custom metadata to provide additional context. | ### Schema Object diff --git a/datacontract.schema.json b/datacontract.schema.json index f5611c7..4cc511e 100644 --- a/datacontract.schema.json +++ b/datacontract.schema.json @@ -5,6 +5,7 @@ "dataContractSpecification": { "type": "string", "enum": [ + "0.9.2", "0.9.1", "0.9.0" ], @@ -266,9 +267,9 @@ "additionalProperties": { "type": "object", "properties": { - "$ref": { + "description": { "type": "string", - "description": "A reference URI to a definition in the specification, internally or externally. Properties will be inherited from the definition." + "description": "An optional string describing the semantic of the data in this field." }, "type": { "type": "string", @@ -290,9 +291,35 @@ "null" ] }, - "description": { + "required": { + "type": "boolean", + "default": false, + "description": "An indication, if this field must contain a value and may not be null." + }, + "unique": { + "type": "boolean", + "default": false, + "description": "An indication, if the value must be unique within the model." + }, + "minLength": { + "type": "number", + "description": "A value must greater than, or equal to, the value of this. Only applies to string types." + }, + "maxLength": { + "type": "number", + "description": "A value must less than, or equal to, the value of this. Only applies to string types." + }, + "format": { "type": "string", - "description": "An optional string describing the semantic of the data in this field." + "description": "A specific format the value must comply with (e.g., 'email', 'uri', 'uuid')." + }, + "pattern": { + "type": "string", + "description": "A regular expression the value must match. Only applies to string types." + }, + "example": { + "type": "string", + "description": "An example value for this field." }, "pii": { "type": "boolean", @@ -309,6 +336,10 @@ "type": "string" }, "description": "Custom metadata to provide additional context." + }, + "$ref": { + "type": "string", + "description": "A reference URI to a definition in the specification, internally or externally. Properties will be inherited from the definition." } } } @@ -316,6 +347,83 @@ } } }, + "definitions": { + "description": "Clear and concise explanations of syntax, semantic, and classification of business objects in a given domain.", + "type": "object", + "minProperties": 1, + "propertyNames": { + "pattern": "^[a-zA-Z0-9_-]+$" + }, + "additionalProperties": { + "domain": { + "type": "string", + "description": "The domain in which this definition is valid.", + "default": "global" + }, + "name": { + "type": "string", + "description": "The technical name of this definition." + }, + "title": { + "type": "string", + "description": "The business name of this definition." + }, + "description": { + "type": "string", + "description": "Clear and concise explanations related to the domain." + }, + "type": { + "type": "string", + "description": "The logical data type." + }, + "required": { + "type": "boolean", + "default": false, + "description": "An indication if this field must contain a value and may not be null." + }, + "unique": { + "type": "boolean", + "default": false, + "description": "An indication if the value must be unique within the model." + }, + "minLength": { + "type": "number", + "description": "A value must be greater than or equal to this value. Applies only to string types." + }, + "maxLength": { + "type": "number", + "description": "A value must be less than or equal to this value. Applies only to string types." + }, + "format": { + "type": "string", + "description": "Specific format requirements for the value (e.g., 'email', 'uri', 'uuid')." + }, + "pattern": { + "type": "string", + "description": "A regular expression pattern the value must match. Applies only to string types." + }, + "example": { + "type": "string", + "description": "An example value." + }, + "pii": { + "type": "boolean", + "description": "Indicates if the field contains Personal Identifiable Information (PII)." + }, + "classification": { + "type": "string", + "description": "The data class defining the sensitivity level for this field." + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Custom metadata to provide additional context." + } + }, + "required": ["name", "type"] + }, "schema": { "type": "object", "properties": { From 5671e0966dc6f8311fea8296dc7b326965775ada Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 4 Jan 2024 14:10:04 +0100 Subject: [PATCH 2/4] Added format fields --- datacontract.init.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/datacontract.init.yaml b/datacontract.init.yaml index 2d3820b..47fbdaf 100644 --- a/datacontract.init.yaml +++ b/datacontract.init.yaml @@ -2,7 +2,7 @@ dataContractSpecification: 0.9.1 id: my-data-contract-id info: title: My Data Contract - version: 0.0.1 + version: 0.9.2 # description: # owner: # contact: From 5ff5c126774f1767e76217bd712d482c8eccacec Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 4 Jan 2024 14:12:26 +0100 Subject: [PATCH 3/4] Change order --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6c3dbab..702a48b 100644 --- a/README.md +++ b/README.md @@ -341,9 +341,9 @@ The Field Objects describes one field (column, property, nested field) of a data | type | [Data Type](#data-types) | The logical data type of the field. | | required | `boolean` | An indication, if this field must contain a value and may not be null. Default: `false` | | unique | `boolean` | An indication, if the value must be unique within the model. Default: `false` | +| format | `string` | `email`: A value must be complaint to [RFC 5321, section 4.1.2](https://www.rfc-editor.org/info/rfc5321).
`uri`: A value must be complaint to [RFC 3986](https://www.rfc-editor.org/info/rfc3986).
`uuid`: A value must be complaint to [RFC 4122](https://www.rfc-editor.org/info/rfc4122). Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | | minLength | `number` | A value must greater than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | | maxLength | `number` | A value must less than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | -| format | `string` | `email`: A value must be complaint to [RFC 5321, section 4.1.2](https://www.rfc-editor.org/info/rfc5321).
`uri`: A value must be complaint to [RFC 3986](https://www.rfc-editor.org/info/rfc3986).
`uuid`: A value must be complaint to [RFC 4122](https://www.rfc-editor.org/info/rfc4122). Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | | pattern | `string` | A value must be valid according to the [ECMA-262](https://262.ecma-international.org/5.1/) regular expression dialect. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | | example | `string` | An example value. | | pii | `boolean` | An indication, if this field contains Personal Identifiable Information (PII). | @@ -367,9 +367,9 @@ Models fields can refer to definitions using the `$ref` field to link to existin | type | [Data Type](#data-types) | The logical data type | | required | `boolean` | An indication, if this field must contain a value and may not be null. Default: `false` | | unique | `boolean` | An indication, if the value must be unique within the model. Default: `false` | +| format | `string` | `email`: A value must be complaint to [RFC 5321, section 4.1.2](https://www.rfc-editor.org/info/rfc5321).
`uri`: A value must be complaint to [RFC 3986](https://www.rfc-editor.org/info/rfc3986).
`uuid`: A value must be complaint to [RFC 4122](https://www.rfc-editor.org/info/rfc4122). Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | | minLength | `number` | A value must greater than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | | maxLength | `number` | A value must less than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | -| format | `string` | `email`: A value must be complaint to [RFC 5321, section 4.1.2](https://www.rfc-editor.org/info/rfc5321).
`uri`: A value must be complaint to [RFC 3986](https://www.rfc-editor.org/info/rfc3986).
`uuid`: A value must be complaint to [RFC 4122](https://www.rfc-editor.org/info/rfc4122). Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | | pattern | `string` | A value must be valid according to the [ECMA-262](https://262.ecma-international.org/5.1/) regular expression dialect. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | | example | `string` | An example value. | | pii | `boolean` | An indication, if this field contains Personal Identifiable Information (PII). | From fcfe54c1cfda474e664c3d384bbc622cfbd975cc Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 5 Jan 2024 12:43:47 +0100 Subject: [PATCH 4/4] Add enum and numeric validations. --- README.md | 39 ++++++++++++++++++++++----------------- datacontract.schema.json | 24 ++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 702a48b..f1ddaef 100644 --- a/README.md +++ b/README.md @@ -358,23 +358,28 @@ The Definition Object includes a clear and concise explanations of syntax, seman It serves as a reference for a common understanding of terminology, ensure consistent usage and to identify join-able fields. Models fields can refer to definitions using the `$ref` field to link to existing definitions and avoid duplicate documentations. -| Field | Type | Description | -|----------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| domain | `string` | The domain in which this definition is valid. Default: `global`. | -| name | `string` | The technical name of this definition. | -| title | `string` | The business name of this definition. | -| description | `string` | Clear and concise explanations related to the domain | -| type | [Data Type](#data-types) | The logical data type | -| required | `boolean` | An indication, if this field must contain a value and may not be null. Default: `false` | -| unique | `boolean` | An indication, if the value must be unique within the model. Default: `false` | -| format | `string` | `email`: A value must be complaint to [RFC 5321, section 4.1.2](https://www.rfc-editor.org/info/rfc5321).
`uri`: A value must be complaint to [RFC 3986](https://www.rfc-editor.org/info/rfc3986).
`uuid`: A value must be complaint to [RFC 4122](https://www.rfc-editor.org/info/rfc4122). Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | -| minLength | `number` | A value must greater than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | -| maxLength | `number` | A value must less than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | -| pattern | `string` | A value must be valid according to the [ECMA-262](https://262.ecma-international.org/5.1/) regular expression dialect. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | -| example | `string` | An example value. | -| pii | `boolean` | An indication, if this field contains Personal Identifiable Information (PII). | -| classification | `string` | The data class defining the sensitivity level for this field, according to the organization's classification scheme. | -| tags | Array of `string` | Custom metadata to provide additional context. | +| Field | Type | Description | +|------------------|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| domain | `string` | The domain in which this definition is valid. Default: `global`. | +| name | `string` | The technical name of this definition. | +| title | `string` | The business name of this definition. | +| description | `string` | Clear and concise explanations related to the domain | +| type | [Data Type](#data-types) | The logical data type | +| required | `boolean` | An indication, if this field must contain a value and may not be null. Default: `false` | +| unique | `boolean` | An indication, if the value must be unique within the model. Default: `false` | +| enum | array of `string` | A value must be equal to one of the elements in this array value. Only evaluated if the value is not null. | +| format | `string` | `email`: A value must be complaint to [RFC 5321, section 4.1.2](https://www.rfc-editor.org/info/rfc5321).
`uri`: A value must be complaint to [RFC 3986](https://www.rfc-editor.org/info/rfc3986).
`uuid`: A value must be complaint to [RFC 4122](https://www.rfc-editor.org/info/rfc4122). Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| minLength | `number` | A value must greater than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| maxLength | `number` | A value must less than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| pattern | `string` | A value must be valid according to the [ECMA-262](https://262.ecma-international.org/5.1/) regular expression dialect. Only evaluated if the value is not null. Only applies to unicode character sequences types (`string`, `text`, `varchar`). | +| minimum | `number` | A value of a number must greater than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to numeric values. | +| exclusiveMinimum | `number` | A value of a number must greater than the value of this. Only evaluated if the value is not null. Only applies to numeric values. | +| maximum | `number` | A value of a number must less than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to numeric values. | +| exclusiveMaximum | `number` | A value of a number must less than the value of this. Only evaluated if the value is not null. Only applies to numeric values. | +| example | `string` | An example value. | +| pii | `boolean` | An indication, if this field contains Personal Identifiable Information (PII). | +| classification | `string` | The data class defining the sensitivity level for this field, according to the organization's classification scheme. | +| tags | Array of `string` | Custom metadata to provide additional context. | ### Schema Object diff --git a/datacontract.schema.json b/datacontract.schema.json index 4cc511e..6d7f2cf 100644 --- a/datacontract.schema.json +++ b/datacontract.schema.json @@ -301,6 +301,14 @@ "default": false, "description": "An indication, if the value must be unique within the model." }, + "enum": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true, + "description": "A value must be equal to one of the elements in this array value. Only evaluated if the value is not null." + }, "minLength": { "type": "number", "description": "A value must greater than, or equal to, the value of this. Only applies to string types." @@ -317,6 +325,22 @@ "type": "string", "description": "A regular expression the value must match. Only applies to string types." }, + "minimum": { + "type": "number", + "description": "A value of a number must greater than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to numeric values." + }, + "exclusiveMinimum": { + "type": "number", + "description": "A value of a number must greater than the value of this. Only evaluated if the value is not null. Only applies to numeric values." + }, + "maximum": { + "type": "number", + "description": "A value of a number must less than, or equal to, the value of this. Only evaluated if the value is not null. Only applies to numeric values." + }, + "exclusiveMaximum": { + "type": "number", + "description": "A value of a number must less than the value of this. Only evaluated if the value is not null. Only applies to numeric values." + }, "example": { "type": "string", "description": "An example value for this field."