When creating a new BIS metadata field, you need to define the field’s data type (string, integer, date, and so on) and decide whether or not you want to apply validation rules or restriction types to the new field. For example, for your collection metadata fields, you can have a custom integer field for the survey vessel’s displacement and have a restriction in place that defines a valid range of values.
There are five different field types recognized by ArcGIS for Maritime: Bathymetry for the collection and extended metadata configuration XML schemas. Each field type has a corresponding data type when viewing the XML schemas directly.
| Metadata Configuration Editor Field Type | XML Schema Data Type |
|---|---|
Date | xmlTypeDateTime |
Double | xmlTypeDouble |
Enumeration | xmlTypeEnum |
Integer | xmlTypeLong |
Text | xmlTypeString |
Each data type has an associated data type restriction that limits the values that can be entered when you edit a field’s value within the Manage Collections or Add Bathymetry dialog boxes, or define a filter in the Explore Bathymetry window (minimum string length, a range of numbers for an integer value, and so on).
When defining a data type restriction for a specific data type, you will need to input specific child elements under the xmlDataRestriction element. You can also use a RelationRestriction, which adds business logic to field entries. These relational restrictions can be applied between two different fields. For example, you can ensure that an end date is not earlier than a start date.
Data types and restrictions
The following are all the data types and data type restrictions you can use when creating a custom metadata field. Each data type and data type restriction has examples on how to configure them in the XML file.
xmlTypeDateTime
This data type is used for date and time entries.
The data type restriction is XmlMetadataFieldDateTimeRestrictionEditable and is used for editable date/time fields.
The following table summarizes the options for the data type restriction.
| Options | Description | Entries | Examples |
|---|---|---|---|
DefaultValue (optional) | The default value that is automatically displayed when new metadata is entered from a BIS tool. | Now: Defaults to the current system date and time in dialog boxes such as Add Bathymetry where a date field can be supplied by the user. | <DefaultValue>Now</DefaultValue> |
RelationRestrictions (optional) | Applies business rules on the field or between two fields. It implements the XmlRelationRestriction child element that defines the relation type and can be linked to another field for which to run the relationship check. |
| relationXmlNodeName example: For start and end date fields, the relationXmlNodeName could be the end date field. |
Example of xmlTypeDateTime and its restrictions
<BisExtXmlMetadataDefinitionField xmlNodeName=”startDate” title=”Start Date” dataType=”xmlTypeDateTime” required=”false” searchable=”true” displayed=”true”>
<xmlDataRestriction restrictionType=”XmlMetadataFieldDateTimeRestrictionEditable”>
<DefaultValue>Now</DefaultValue>
<RelationRestrictions>
<XmlRelationRestriction relationType="LessThanOrEqual" relationXmlNodeName="endDate" />
<RelationRestrictions>
</xmlDataRestriction>
</BisExtXmlMetadataDefinitionField>
xmlTypeDouble
This data type is used for double-precision numeric values (3.2, 5.4545, and so on), and its value range is from -1.79769e+308 to 1.79769e308. You can define a default value, maximum and minimum values, and set the total number of decimal places.
The data type restriction is XmlMetadataFieldDoubleRestriction and is used for editable double fields.
The following table summarizes the options for the data type restriction.
| Options | Description | Entries | Examples |
|---|---|---|---|
DefaultValue (optional) | The initial value shown in the field display. | N/A | <DefaultValue>1.123</DefaultValue> |
MaxDecimalPlaces (optional) | Defines the maximum number of decimal places allowed for a double value. If this is not defined, then the limit will be based on the native double type limitation. Never reduce a value if you have already entered data into the metadata fields since this will result in editing errors in the application. | N/A | <MaxDecimalPlaces>6</MaxDecimalPlaces> |
MinValue (optional) | Defines a minimum value allowed when editing the metadata field within the user interface. You should not change it to a value greater than the original because this can cause data editing errors. | N/A | <MinValue>2.1</MinValue> |
MaxValue (optional) | Defines the maximum value allowed when editing the metadata field within the user interface. You should not change it to a value lower than the original if values have been populated on the metadata fields because this will cause editing errors. | N/A | <MaxValue>5.6</MaxValue> |
RelationRestrictions (optional) | Applies business rules on the field or between two fields. It implements the XmlRelationRestriction child element that defines the relation type and can be linked to another field for which to run the relationship check. |
| A double field representing a Depth value can be greater than a value defined as a minimum depth. |
Example of xmlTypeDouble and its restrictions
<BisExtXmlMetadataDefinitionField xmlNodeName=”averageDepth” title=”Average Depth” dataType=”xmlDoubleType” required=”false” searchable=”true” displayed=”true”>
<xmlDataRestriction restrictionType=”XmlMetadataFieldDoubleRestriction”>
<DefaultValue>1.1234</DefaultValue>
<MaxDecimalPlaces>6</MaxDecimalPlaces>
<MinValue>2.1</MinValue>
<MaxValue>5.6</MaxValue>
<RelationRestrictions>
<XmlRelationRestriction relationType="GreaterThan" relationXmlNodeName="minimumDepth" />
<RelationRestrictions>
</xmlDataRestriction>
</BisExtXmlMetadataDefinitionField>
xmlTypeEnum
This data type stores a list of enumerated values that display as a list of options for your custom field.
The data type restriction is XmlMetadataFieldEnumRestriction and is used for editable option list values that are assigned to a metadata field. For example, you could choose from a list of five sensors that you assign to a sensor metadata field. Over time, you could add to the list of available sensors.
The following table summarizes the options for the data type restriction.
| Options | Description | Entries | Examples |
|---|---|---|---|
DefaultValue (optional) | Displays the defined value, based on the id value set on the EnumValues element, from the enumerated list. If you select a specific option most of the time, you can set that option as the default value. | N/A | <DefaultValue>1</DefaultValue> |
EnumValues (required) | The parent element for the EnumValue element that holds the detailed information for the list values. | N/A | N/A |
EnumValue (required) | Stores the id and text attributes. Once you have set an enumerated value to a metadata record, you can no longer remove an EnumValue element from the configuration file because this will cause metadata editing errors. If you need to show that an enumerated value is no longer valid or applicable, you can update the text attribute to show this status. The order in which the EnumValue elements are listed is the order they will appear in the field's drop-down list. |
| <EnumValues> <EnumValue id="0" text="Option 1" /> <EnumValue id="2" text="Option 3" /> <EnumValue id="1" text="Option 2 (deprecated)" /> </EnumValues> |
RelationRestrictions (optional) | Applies business rules on the field or between two fields. It implements the XmlRelationRestriction child element that defines the relation type and can be linked to another field for which to run the relationship check. |
| relationXmlNodeName: For example, the selection of a sensor type from the list of available sensors can be required when the Frequency field is defined or is not Null. |
Example of xmlTypeEnum and its restrictions
<BisExtXmlMetadataDefinitionField xmlNodeName=”sensor” title=”Sensor” dataType=”xmlTypeEnum” required=”true” searchable=”true” displayed=”true”>
<xmlDataRestriction restrictionType=”XmlMetadataFieldEnumRestriction”>
<EnumValues>
<EnumValue id="0" text="Sensor 1" />
<EnumValue id="1" text="Sensor 2" />
<EnumValue id="2" text="Sensor 3" />
</EnumValues>
<RelationRestrictions>
<XmlRelationRestriction relationType="RequiredWhenOtherIsNotNull" relationXmlNodeName="sonarFrequency" />
<RelationRestrictions>
</xmlDataRestriction>
</BisExtXmlMetadataDefinitionField>
xmlTypeInt
This data type is used for standard integer values (2, 545, and so on), and its default value range is from -2147483648 to 2147483648. The default, minimum, and maximum values can be defined to suit your needs as long as it falls within this range.
The data type restriction is XmlMetadataFieldIntRestriction and is used for editable integer fields.
The following table summarizes the options for the data type restriction.
| Options | Description | Entries | Examples |
|---|---|---|---|
DefaultValue (optional) | The initial value shown in the application display. If you need to input a negative integer, be sure to use the proper signage for the regional setting you are in (that is -1 for US and 1- for certain Arabic settings). | N/A | <DefaultValue>1</DefaultValue> |
MinValue (optional) | Defines a minimum value allowed when editing the metadata field. You should not change it to a value greater than the original because this can cause data editing errors. | N/A | <MinValue>0</MinValue> |
MaxValue (optional) | Defines the maximum value allowed when editing the metadata field within the user interface. You should not change it to a value lower than the original if values have been populated on the metadata fields because this will cause editing errors. | N/A | <MaxValue>100</MaxValue> |
RelationRestrictions (optional) | Applies business rules on the field or between two fields. It implements the XmlRelationRestriction child element that defines the relation type and can be linked to another field for which to run the relationship check. |
| relationXmlNodeName: For example, you can require a field representing a vessel's number of tracks to be greater than the minimum number of tracks for a vessel; you can also add another restriction that requires the number of tracks to be populated when the vessel field is populated or is not Null. |
Example of xmlTypeInt and its restrictions
<BisExtXmlMetadataDefinitionField xmlNodeName="vesselTracks" title=”Number of Vessel Tracks” dataType=”xmlTypeInt” required=”false” searchable=”true” displayed=”true”>
<xmlDataRestriction restrictionType=”XmlMetadataFieldIntRestriction”>
<DefaultValue>1</DefaultValue>
<MinValue>0</MinValue>
<MaxValue>100</MaxValue>
<RelationRestrictions>
<XmlRelationRestriction relationType="GreaterThan" relationXmlNodeName="minVesselTrackReq" />
<XmlRelationRestriction relationType="RequiredWhenOtherIsNotNull" relationXmlNodeName="vesselName" />
<RelationRestrictions>
</xmlDataRestriction>
</BisExtXmlMetadataDefinitionField>
xmlTypeShort
A data type used for short integer fields. The range for short integers is -32768 to 32767. You can set default, minimum, and maximum values.
The data type restriction is XmlMetadataFieldShortRestriction and is used to apply a variety of options available for short integer metadata fields.
The following table summarizes the options for the data type restriction.
| Options | Description | Entries | Examples |
|---|---|---|---|
DefaultValue (optional) | The initial value shown in the application display. If you need to input a negative integer, be sure to use the proper signage for the regional setting you are in (that is -1 for US and 1- for certain Arabic settings). | N/A | <DefaultValue>1</DefaultValue> |
MinValue (optional) | Defines a minimum value allowed when editing the metadata field. You should not alter the value if you have added bathymetry data to your BIS geodatabase and defined values for the field because this can cause data editing errors. | N/A | <MinValue>1</MinValue> |
MaxValue (optional) | Defines the maximum value allowed when editing the metadata field within the user interface. You should not alter the value if you have added bathymetry data to your BIS geodatabase and defined values for the field because this will cause editing errors. | N/A | <MaxValue>25</MaxValue> |
RelationRestrictions (optional) | Applies business rules on the field or between two fields. It implements the XmlRelationRestriction child element that defines the relation type and can be linked to another field for which to run the relationship check. |
| relationXmlNodeName: For example, you can require a vessel number to be populated when the vessel field is populated or is not Null. |
Example of xmlTypeShort and its restrictions
<BisExtXmlMetadataDefinitionField xmlNodeName="vesselNumber" title=”Vessel Number” dataType=”xmlTypeShort” required=”false” searchable=”true” displayed=”true”>
<xmlDataRestriction restrictionType=”XmlMetadataFieldShortRestriction”>
<DefaultValue>1</DefaultValue>
<MinValue>1</MinValue>
<MaxValue>25</MaxValue>
<RelationRestrictions>
<XmlRelationRestriction relationType="RequiredWhenOtherIsNotNull" relationXmlNodeName="vesselName" />
<RelationRestrictions>
</xmlDataRestriction>
</BisExtXmlMetadataDefinitionField>
xmlTypeLong
This is a data type used for integers that hold a range of -9223372036854775808 to 9223372036854775807. You can set default, minimum, and maximum values.
The data type restriction is XmlMetadataFieldLongRestriction and is used to provide metadata editing and display rules for long integer field types.
The following table summarizes the options for the data type restriction.
| Options | Description | Entries | Examples |
|---|---|---|---|
DefaultValue (optional) | The initial value shown in the application display. If you need to input a negative integer, be sure to use the proper signage for the regional setting to which your system is set (that is -1 for US and 1- for certain Arabic settings). | N/A | <DefaultValue>1</DefaultValue> |
MinValue (optional) | Defines a minimum value allowed when editing the metadata field. You should not alter the value if you have added bathymetry data to your BIS geodatabase and defined values for the field because this can cause data editing errors. | N/A | <MinValue>1</MinValue> |
MaxValue (optional) | Defines the maximum value allowed when editing the metadata field within the user interface. You should not alter the value if you have added bathymetry data to your BIS geodatabase and defined values for the field because this will cause editing errors. | N/A | <MaxValue>25</MaxValue> |
RelationRestrictions (optional) | Applies business rules on the field or between two fields. It implements the XmlRelationRestriction child element that defines the relation type and can be linked to another field for which to run the relationship check. |
| relationXmlNodeName: For example, a restriction could require that the vessel displacement is populated when the vessel field is populated or is not Null. |
Example of xmlTypeLong and its restrictions
<BisExtXmlMetadataDefinitionField xmlNodeName="vesselDisplacement" title=”Vessel Displacement” dataType=”xmlTypeLong” required=”false” searchable=”true” displayed=”true”>
<xmlDataRestriction restrictionType=”XmlMetadataFieldLongRestriction”>
<DefaultValue>10000</DefaultValue>
<MinValue>10000</MinValue>
<MaxValue>25000000</MaxValue>
<RelationRestrictions>
<XmlRelationRestriction relationType="RequiredWhenOtherIsNotNull" relationXmlNodeName="vesselName" />
<RelationRestrictions>
</xmlDataRestriction>
</BisExtXmlMetadataDefinitionField>
xmlTypeString
This is a data type used for standard string metadata fields. Text values entered for a string field which represent hyperlinks, such as web URLs or UNC paths to on-disk files or folders, will automatically be recognized and enabled.
The data type restriction is XmlMetadataFieldStringRestriction and is used to describe metadata editing and display rules for string fields. You have the option to set a default value for the field and define a minimum and maximum string value length. For example, you can enforce that a string value does not exceed 255 characters.
The following table summarizes the options for the data type restriction.
| Options | Description | Entries | Examples |
|---|---|---|---|
DefaultValue (optional) | The initial value shown in the field display. | N/A | <DefaultValue>Esri</DefaultValue> |
MinLength (optional) | Defines a minimum string length for the metadata field. You should not alter the value if you have added bathymetry data to your BIS geodatabase and defined values for the field because this can cause data editing errors. | N/A | <MinLength>1</MinLength> |
MaxLength (optional) | Defines the maximum length for the metadata field. You should not alter the value if you have added bathymetry data to your BIS geodatabase and defined values for the field because this will cause editing errors. | N/A | <MaxLength>255</MaxLength> |
RelationRestrictions (optional) | Applies business rules on the field or between two fields. It implements the XmlRelationRestriction child element that defines the relation type and can be linked to another field for which to run the relationship check. |
| relationXmlNodeName: For example, a restriction could require a string field representing a contact organization to be populated when a contact person is defined. |
Example of xmlTypeString and its restrictions
<BisExtXmlMetadataDefinitionField xmlNodeName="contactOrganization" title=”Contact Organization” dataType=”xmlTypeString” required=”true” searchable=”true” displayed=”true”>
<xmlDataRestriction restrictionType=”XmlMetadataFieldStringRestriction”>
<DefaultValue>Esri</DefaultValue>
<MinLength>1</MinLength>
<MaxLength>255</MaxLength>
<RelationRestrictions>
<XmlRelationRestriction relationType="RequiredWhenOtherIsNotNull" relationXmlNodeName="contactPerson" />
<RelationRestrictions>
</xmlDataRestriction>
</BisExtXmlMetadataDefinitionField>
Relation restrictions and types
The collection and extended metadata fields have relation restrictions that are used to enforce your organization’s specific business rules. Relation restrictions validate your business rules by comparing one metadata field value to another and applying a rule between the two fields, which is defined as a relation type. For example, one relation type checks whether one numeric field is greater than another or whether a metadata field is populated correctly based on the value of another metadata field.
There are two types of relation restrictions that you can apply to a new metadata field: basic and numeric. The basic type is used for string and enumerated metadata fields and the numeric type is applied to all numeric data types (date, double, and integer). If you declare a relation restriction element, then you must apply at least one relation restriction type, but there is no limit to the number of relation restriction types you can set for a metadata field. A relation restriction type implements the following required attributes:
- relationType—Defines the type of relation being applied to the metadata field
- relationXmlNodeName—Defines the xmlNodeName of another metadata field stored within the configuration XML toward which the relationType is applied
In the next example, the metadata value stored in the xmlNodeName="vesselTracks" field will be compared to the metadata value stored in the relationXmlNodeName="vesselName" field, which corresponds to a field defined in the XML configuration file. The RelationRestriction element, subelements and attributes link the two fields where the relationType attribute defines the type of check that will be run against the two metadata fields. In this example, there are two relation types being run: GreaterThan and RequiredWhenOtherIsNotNull.
Example of RelationRestriction element
<BisExtXmlMetadataDefinitionField xmlNodeName="vesselTracks" title=”Number of Vessel Tracks” dataType=”xmlTypeInt” required=”false” searchable=”true” displayed=”true”>
<xmlDataRestriction restrictionType=”XmlMetadataFieldIntRestriction”>
<DefaultValue>1</DefaultValue>
<MinValue>0</MinValue>
<MaxValue>100</MaxValue>
<RelationRestrictions>
<XmlRelationRestriction relationType="GreaterThan" relationXmlNodeName="minVesselTrackReq" />
<XmlRelationRestriction relationType="RequiredWhenOtherIsNotNull" relationXmlNodeName="vesselName" />
<RelationRestrictions>
</xmlDataRestriction>
</BisExtXmlMetadataDefinitionField>
The following are the available relation types in the schema.
| Relation Restriction Type | Description | Example |
|---|---|---|
RequiredWhenOtherIsNotNull | The metadata field defined in the xmlNodeName attribute must be populated when the metadata field defined in the relationXmlNodeName attribute holds a value. If no value is entered in the field defined in the relationXmlNodeName attribute, then the relation type will not be applied. | <RelationRestrictions> <XmlRelationRestriction relationType="RequiredWhenOtherIsNotNull" relationXmlNodeName="stringMinimumRequired" /> <XmlRelationRestriction relationType="RequiredWhenOtherIsNotNull" relationXmlNodeName="stringSomeOptions" /> </RelationRestrictions> |
Basic Relation Restriction types
| Relation Restriction Type | Description | Example |
|---|---|---|
LessThan | The metadata field defined in the xmlNodeName attribute must be less than the value defined in the relationXmlNodeName attribute. If no value is entered in the field defined in the relationXmlNodeName attribute, then the relation type will not be applied. | <RelationRestrictions> <XmlRelationRestriction relationType="LessThan"relationXmlNodeName="intMinimumRequired" /> </RelationRestrictions> |
LessThanOrEqual | The metadata field defined in the xmlNodeName must be less than or equal to the value defined in the relationXmlNodeName attribute. If no value is entered in the field defined in the relationXmlNodeName attribute, then the relation type will not be applied. | <RelationRestrictions> <XmlRelationRestriction relationType=" LessThanOrEqual" relationXmlNodeName="intMinimumRequired" /> </RelationRestrictions> |
Equal | The metadata field defined in the xmlNodeName attribute must be equal to the value defined in the relationXmlNodeName attribute. If no value is entered in the field defined in the relationXmlNodeName attribute, then the relation type will not be applied. | <RelationRestrictions> <XmlRelationRestriction relationType=" Equal" relationXmlNodeName="intMinimumRequired" /> </RelationRestrictions> |
GreaterThan | The metadata field defined in the xmlNodeName attribute must be greater than the value defined in the relationXmlNodeName attribute. If no value is entered in the field defined in the relationXmlNodeName attribute, then the relation type will not be applied. | <RelationRestrictions> <XmlRelationRestriction relationType=" GreaterThan" relationXmlNodeName="intMinimumRequired" /> </RelationRestrictions> |
GreaterThanOrEqual | The metadata field defined in the xmlNodeName attribute must be greater than or equal to the value defined in the relationXmlNodeName attribute. If no value is entered in the field defined in the relationXmlNodeName attribute, then the relation type will not be applied. | <RelationRestrictions> <XmlRelationRestriction relationType=" GreaterThanOrEqual" relationXmlNodeName="intMinimumRequired" /> </RelationRestrictions> |
RequiredWhenOtherIsNotNull | The metadata field defined in the xmlNodeName attribute must be populated when the metadata field defined in the relationXmlNodeName attribute holds a value. If no value is entered in the field defined in the relationXmlNodeName attribute, then the relation type will not be applied. | <RelationRestrictions> <XmlRelationRestriction relationType="RequiredWhenOtherIsNotNull" relationXmlNodeName="intMinimumRequired" /> </RelationRestrictions> |
Numeric Relation Restriction types