5.2 Schema
The schema metadata object and its contents provides information about the structure of the data provided.
5.2.1 Requirements
5.2.1.1 Reference to FOCUS Data
FOCUS data artifacts, whether they are data files, data streams, or data tables, MUST provide a clear reference to the schema of the data. This reference MUST be retrievable without inspection of the contents of the FOCUS data within the data artifact. For some delivery mechanisms such as database tables, the provider may rely on the schema functionality of the providing system.
It is recommended that the schema reference be provided as an external reference rather than included in full as metadata accompanying the data artifact. This allows for easier understanding of when changes to the schema of the FOCUS datasets occurs.
5.2.1.2 Schema Metadata Creation
Should the provider change the structure of the supplied FOCUS data artifact, a new schema metadata object MUST be supplied. These scenarios include, but are not limited to:
- Adding a new column
- Removing a column
- Changing column metadata
- FOCUS Version has changed
- Data Generator Version has changed
- Correcting schema metadata errors
5.2.1.3 Schema Metadata Updates
Should there be an error where the schema metadata object does not match the schema of the FOCUS data artifact, the provider MUST update the schema metadata object to match the schema of the FOCUS data artifact. This is to ensure that the schema metadata object is always accurate.
5.2.2 Schema Example
For an example of the FOCUS schema metadata please refer to: Schema Metadata Example
5.2.3 Schema ID
The Schema ID provides the reference item to associate which Schema was used for the generation of a FOCUS Dataset.
The SchemaId MUST be present in the metadata. The SchemaId MUST be of String. It is RECOMMENDED for SchemaId to be a Globally Unique Identifier (GUID).
5.2.3.1 Metadata ID
SchemaId
5.2.3.2 Metadata Name
Schema ID
5.2.3.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Mandatory |
| Allows nulls | False |
| Data type | STRING |
| Value format | Recommend GUID String |
5.2.3.4 Introduced (version)
1.0
5.2.4 Creation Date
Date the schema was created.
The CreationDate MUST be present in the metadata. This MUST be of type Date/Time and MUST NOT contain null values. CreationDate MUST conform to DateTimeFormat.
5.2.4.1 Metadata ID
CreationDate
5.2.4.2 Metadata Name
Creation Date
5.2.4.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Mandatory |
| Allows nulls | False |
| Data type | Date/Time |
| Value format | Date/Time Format |
5.2.4.4 Introduced (version)
1.0
5.2.5 FOCUS Version
The version of FOCUS utilized for building the dataset.
The FocusVersion MUST be provided in the metadata. FocusVersion MUST be of type String and MUST NOT contain null values. FocusVersion MUST match one of the published versions of the FOCUS specification. FocusVersion MUST match the version of the FOCUS specification that the FOCUS dataset conforms to.
5.2.5.1 Metadata ID
FocusVersion
5.2.5.2 Metadata Name
FOCUS Version
5.2.5.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Mandatory |
| Allows nulls | False |
| Data type | STRING |
| Value format | Must align with a published FocusVersion |
5.2.5.4 Introduced (version)
1.0
5.2.6 Data Generator Version
The DataGeneratorVersion MAY be supplied to declare the version of logic by which the FOCUS dataset was generated and is separate from FOCUS Version. DataGeneratorVersion allows for the provider to specify changes that may not result in a structural change in the data. It is suggested that the DataGeneratorVersion use a versioning approach such as SemVer version.
The DataGeneratorVersion column adheres to the following requirements:
- DataGeneratorVersion MAY be present in FOCUS metadata.
- DataGeneratorVersion MUST be of type String.
- DataGeneratorVersion MUST conform to StringHandling requirements.
- DataGeneratorVersion MUST NOT be null.
- When FocusVersion is changed, a new DataGeneratorVersion MUST be also changed.
- Data generators MUST document what changes are present in the DataGeneratorVersion.
5.2.6.1 Metadata ID
DataGeneratorVersion
5.2.6.2 Metadata Name
Data Generator Version
5.2.6.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Optional |
| Allows nulls | False |
| Data type | STRING |
| Value format | <not specified> |
5.2.6.4 Introduced (version)
1.1
5.2.7 Column Definition
The FOCUS metadata schema column definition provides a list of the columns present in the FOCUS dataset along with metadata about the columns.
5.2.7.1 Requirements
This metadata MUST be present in the FOCUS metadata schema. This metadata MUST be of type Object and MUST NOT contain null values.
5.2.7.2 Column Name
The name of the column provided in the FOCUS dataset.
The ColumnName MUST be provided in the FOCUS Metadata schema. ColumnName MUST be of type String and MUST NOT contain null values.
5.2.7.2.1 Metadata ID
ColumnName
5.2.7.2.2 Metadata Name
Column Name
5.2.7.2.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Mandatory |
| Allows nulls | False |
| Data type | String |
| Value format | <not specified> |
5.2.7.2.4 Introduced (version)
1.0
5.2.7.3 Data Type
The data type of the column provided in the FOCUS dataset.
The DataType MUST be provided in the FOCUS Metadata schema. DataType MUST be of type String and MUST NOT contain null values.
5.2.7.3.1 Metadata ID
DataType
5.2.7.3.2 Metadata Name
Data Type
5.2.7.3.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Mandatory |
| Allows nulls | False |
| Data type | String |
| Value format | <not specified> |
5.2.7.3.4 Introduced (version)
1.0
5.2.7.4 Deprecated
The deprecation status of any column in a FOCUS dataset.
Deprecated MUST be provided in the FOCUS Metadata schema when a column will be removed in a future delivered schema definition. DataType MUST be of type Boolean and MUST NOT contain null values. The value of deprecated should only be "true" if the column is deprecated. Providers can choose to always provide the deprecation key or elect to only include it when the deprecation status of a column is "true". Deprecated must be "true" when the provider removes a column at a future date, or the column has been identified for deprecation for the FOCUS version identified in the schema definition.
5.2.7.4.1 Metadata ID
Deprecated
5.2.7.4.2 Metadata Name
Deprecated
5.2.7.4.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | Boolean |
| Value format | <not specified> |
5.2.7.4.4 Introduced (version)
1.2
5.2.7.5 Numeric Precision
Numeric Precision is the maximum number of digits for the values in the column.
NumericPrecision SHOULD be provided in the FOCUS Metadata schema for Numeric Format columns. NumericPrecision MUST be of type Integer and MUST NOT contain null values.
5.2.7.5.1 Metadata ID
NumericPrecision
5.2.7.5.2 Metadata Name
Numeric Precision
5.2.7.5.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | Integer |
| Value format | Numeric Format |
5.2.7.5.4 Introduced (version)
1.0
5.2.7.6 Number Scale
The number scale of the data provides the maximum number of digits after the decimal point in decimal numbers.
NumberScale SHOULD be provided in the FOCUS Metadata schema for Decimal columns. NumberScale MUST be of type Integer and MUST NOT contain null values.
5.2.7.6.1 Metadata ID
NumberScale
5.2.7.6.2 Metadata Name
Number Scale
5.2.7.6.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | Integer |
| Value format | Numeric Format |
5.2.7.6.4 Introduced (version)
1.0
5.2.7.7 PreviousColumnName
The PreviousColumnName field indicates that on that schema the column where the key is included was renamed.
In cases where the PreviousColumnName is present, the following applies:
- PreviousColumnName MUST not be null.
- PreviousColumnName MUST be of type String.
- PreviousColumnName MUST be the name used in previous versions of the schema.
- PreviousColumnName MUST NOT be present in schema versions created after the rename.
5.2.7.7.1 Metadata ID
PreviousColumnName
5.2.7.7.2 Metadata Name
Previous Column Name
5.2.7.7.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | String |
| Value format | <not specified> |
5.2.7.7.4 Introduced (version)
1.2
5.2.7.8 Provider Tag Prefixes
The Provider Tag Prefixes define the list of prefixes used in the tag name of provider-defined tags. This metadata is useful for the consumer to identify which tags are provider-defined vs user-defined.
The ProviderTagPrefixes MUST be provided when ColumnName is equal to Tags. The ProviderTagPrefix MUST be of type Array of Strings. The ProviderTagPrefixes SHOULD be easily associated with the provider who generated the FOCUS dataset.
5.2.7.8.1 Metadata ID
ProviderTagPrefixes
5.2.7.8.2 Metadata Name
Provider Tag Prefixes
5.2.7.8.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | Array |
| Value format | STRING datatype values in the array |
5.2.7.8.4 Introduced (version)
1.0
5.2.7.9 String Encoding
The string encoding scheme of the column provided in the FOCUS dataset.
StringEncoding SHOULD be provided in the FOCUS Metadata schema when it is required to know this information in order to successfully read the data. StringEncoding MUST be of type String and MUST NOT contain null values.
5.2.7.9.1 Metadata ID
StringEncoding
5.2.7.9.2 Metadata Name
StringEncoding
5.2.7.9.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | String |
| Value format | <not specified> |
5.2.7.9.4 Introduced (version)
1.0
5.2.7.10 String Max Length
The string max length of the data that can be stored in the column.
StringMaxLength SHOULD be provided in the FOCUS Metadata schema for String columns. StringMaxLength MUST be of type Integer and MUST NOT contain null values.
5.2.7.10.1 Metadata ID
StringMaxLength
5.2.7.10.2 Metadata Name
String Max Length
5.2.7.10.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | Integer |
| Value format | Numeric Format |
5.2.7.10.4 Introduced (version)
1.0