4.2 Schema
The schema metadata object and its contents provides information about the structure of the data provided.
4.2.1 Requirements
4.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.
4.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
- Provider Version has changed
- Correcting schema metadata errors
4.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.
4.2.2 Schema Example
For an example of the FOCUS schema metadata please refer to: Schema Metadata Example
4.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).
4.2.3.1 Metadata ID
SchemaId
4.2.3.2 Metadata Name
Schema ID
4.2.3.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Mandatory |
| Allows nulls | False |
| Data type | STRING |
| Value format | Recommend GUID String |
4.2.3.4 Introduced (version)
1.0
4.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.
4.2.4.1 Metadata ID
CreationDate
4.2.4.2 Metadata Name
Creation Date
4.2.4.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Mandatory |
| Allows nulls | False |
| Data type | Date/Time |
| Value format | Date/Time Format |
4.2.4.4 Introduced (version)
1.0
4.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.
4.2.5.1 Metadata ID
FocusVersion
4.2.5.2 Metadata Name
FOCUS Version
4.2.5.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Mandatory |
| Allows nulls | False |
| Data type | STRING |
| Value format | Must align with a published FocusVersion |
4.2.5.4 Introduced (version)
1.0
4.2.6 Provider Version
The ProviderVersion MAY be supplied to declare the version of logic by which the FOCUS dataset was generated and is separate from FOCUS Version. ProviderVersion allows for the provider to specify changes that may not result in a structural change in the data. It is suggested that the provider version use a versioning approach such as SemVer version.
ProviderVersion MUST be of type String and MUST NOT contain null values. If FocusVersion is changed a new ProviderVersion MUST be also changed. The provider MUST document what changes are present in the ProviderVersion.
4.2.6.1 Metadata ID
ProviderVersion
4.2.6.2 Metadata Name
Provider Version
4.2.6.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Optional |
| Allows nulls | False |
| Data type | STRING |
| Value format | <not specified> |
4.2.6.4 Introduced (version)
1.1
4.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.
4.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.
4.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.
4.2.7.2.1 Metadata ID
ColumnName
4.2.7.2.2 Metadata Name
Column Name
4.2.7.2.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Mandatory |
| Allows nulls | False |
| Data type | String |
| Value format | <not specified> |
4.2.7.2.4 Introduced (version)
1.0
4.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.
4.2.7.3.1 Metadata ID
DataType
4.2.7.3.2 Metadata Name
Data Type
4.2.7.3.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Mandatory |
| Allows nulls | False |
| Data type | String |
| Value format | <not specified> |
4.2.7.3.4 Introduced (version)
1.0
4.2.7.4 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.
4.2.7.4.1 Metadata ID
NumericPrecision
4.2.7.4.2 Metadata Name
Numeric Precision
4.2.7.4.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | Integer |
| Value format | Numeric Format |
4.2.7.4.4 Introduced (version)
1.0
4.2.7.5 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.
4.2.7.5.1 Metadata ID
NumberScale
4.2.7.5.2 Metadata Name
Number Scale
4.2.7.5.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | Integer |
| Value format | Numeric Format |
4.2.7.5.4 Introduced (version)
1.0
4.2.7.6 Provider Tag Prefixes
The Provider Tag Prefixes defines 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.
4.2.7.6.1 Metadata ID
ProviderTagPrefixes
4.2.7.6.2 Metadata Name
Provider Tag Prefixes
4.2.7.6.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | Array |
| Value format | STRING datatype values in the array |
4.2.7.6.4 Introduced (version)
1.0
4.2.7.7 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.
4.2.7.7.1 Metadata ID
StringEncoding
4.2.7.7.2 Metadata Name
StringEncoding
4.2.7.7.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | String |
| Value format | <not specified> |
4.2.7.7.4 Introduced (version)
1.0
4.2.7.8 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.
4.2.7.8.1 Metadata ID
StringMaxLength
4.2.7.8.2 Metadata Name
String Max Length
4.2.7.8.3 Content constraints
| Constraint | Value |
|---|---|
| Feature level | Conditional |
| Allows nulls | False |
| Data type | Integer |
| Value format | Numeric Format |
4.2.7.8.4 Introduced (version)
1.0