Item classification reference

Overview

Item classification is the process of assigning a series of labels to an item from a predefined list of labels. Specific industries or regions have data privacy laws and data compliance regulations that require items to be classified in order to protect, and control access to, sensitive information. Though the specifics of each data protection law, regulation, or standard may vary, all require that data is classified, and all will perform audits to ensure that organizations are in compliance.

ArcGIS Enterprise administrators (either the default administrator, or an administrator assigned a custom role that includes the Organization website privilege) can define a set of labels that take into account the specific laws or regulations their item classifications need to include. This allows organization members to use those labels to set the level of sensitivity of the data an item has, specify who the information can be accessed by or shared with, and outline when information can be made publicly accessible.

Administrators define these sets of labels through a classification schema. A classification schema is a JSON object that contains a hierarchy of classification and dissemination properties. The schema is provided as a JSON file and assigned to the organization, after which all new items added to the organization, and any preexisting items, must be classified.

While classification schemas can be complex, organizations may benefit from creating an initial schema that focuses on a core number of classification labels that cover broad restriction categories. As time goes on, the schema can be updated to include more classification labels to account for any changes to regulation requirements, for internal classification purposes, or to accommodate any new regulations the organization needs to follow.

Defining a classification schema

A classification schema is made up of four sub-objects:

Base properties: the schema's high-level properties.
Classification Metadata: the primary classification label for organization items (e.g. Unclassified, In-confidence, Sensitive, etc.).
Attributes: the various classification and dissemination information used to classify items.
Layouts: the order in which the attributes are presented on the classification form.

Each area is defined in more detail below.

Base properties

A classification schema's base properties are the higher-level properties that define elements of the schema itself and how classification labels will be displayed during and after classification.

The sample code below demonstrates how the base properties have been set up for a specific schema. This sample does not show the full classification schema; the other tabs have code samples that demonstrate more of the schema's syntax.

Use dark colors for code blocksCopy
{
  "name": "academic-institution-classification-schema",
  "version": "2.0",
  "grammarVersion": "2.0",
  "attributeCategories": [],
  "bannerExpression": "function bannerExpression(schemaJsonString, valueJsonString, attributeId) {\n    var valueJson = Dictionary(valueJsonString)\n    var schemaJson = Dictionary(schemaJsonString)\n    var selectionText = \"\"\n    if (HasKey(valueJson, \"classification\")) {\n        selectionText = selectionText + valueJson[\"classification\"]\n        if (HasKey(valueJson, \"distribution\")) {\n            selectionText = selectionText + \"//\" + valueJson[\"distribution\"]\n        }\n        if (HasKey(valueJson, \"reviewDate\") && valueJson[\"classification\"] != \"Unclassified\") {\n            selectionText = selectionText + \"/\" + \"To be reviewed on\" + \" \" + valueJson[\"reviewDate\"]\n        }\n    }\n    return selectionText;\n}\nbannerExpression(schemaJsonString, valueJsonString, attributeId)",
  "selectionTextExpression": "function selectionTextExpression(schemaJsonString, valueJsonString, attributeId) {\n    var valueJson = Dictionary(valueJsonString)\n    var schemaJson = Dictionary(schemaJsonString)\n    var selectionText = \"\"\n    if (HasKey(valueJson, \"classification\")) {\n        selectionText = selectionText + valueJson[\"classification\"]\n        if (HasKey(valueJson, \"distribution\")) {\n            selectionText = selectionText + \"//\" + valueJson[\"distribution\"]\n        }\n        if (HasKey(valueJson, \"reviewDate\") && valueJson[\"classification\"] != \"Unclassified\") {\n            selectionText = selectionText + \"/\" + \"To be reviewed on\" + \" \" + valueJson[\"reviewDate\"]\n        }\n    }\n    return selectionText;\n}\nselectionTextExpression(schemaJsonString, valueJsonString, attributeId)",
}

There are two properties (bannerExpression and selectionTextExpression) that accept Arcade expressions as an input. The code samples below provide a closer look at Arcade expression examples for each property.

bannerExpression Arcade ExamplebannerExpression Arcade ExampleselectionTextExpression Arcade Example
Use dark colors for code blocksCopy
function bannerExpression(schemaJsonString, valueJsonString, attributeId) {
  var valueJson = Dictionary(valueJsonString);
  var schemaJson = Dictionary(schemaJsonString);
  var selectionText = "";
  if (HasKey(valueJson, "classification")) {
    selectionText = selectionText + valueJson["classification"];
    if (HasKey(valueJson, "distribution")) {
      selectionText = selectionText + "//" + valueJson["distribution"];
    }
    if (HasKey(valueJson, "reviewDate") && valueJson["classification"] != "Unclassified") {
      selectionText = selectionText + "/" + "To be reviewed on" + " " + valueJson["reviewDate"];
Expand

The table below outlines the required and optional base properties for the classification schema.

Property	Required	Description
`name`		Specifies the name of the classification schema. Use dark colors for code blocksCopy `1 "name": "academic-institution-classification-schema",`
`version`		Specifies the version number of the classification schema. The version can be updated each time the classification schema is modified, though the value that should be assigned to represent that update is up to the discretion of organization administrators. Use dark colors for code blocksCopy `1 "version": "2.0",`
`grammarVersion`		Specifies the grammar version the schema classification adheres to. This value must match the current grammar version, which is returned by the Classification resource. Use dark colors for code blocksCopy `1 "grammarVersion": "2.0",`
`helpTooltip`		Sets the help text that is returned whenever a user hovers over the Information button on the classification form. Use dark colors for code blocksCopy `1 "helpTooltip": "Help and usage instructions",`
`helpUrl`		Sets the URL of the schema help document that is opened when a user clicks on the Information button on the classification form. The help document will open up as a new tab. Help documentation is created, maintained, and hosted by the organization and is not provided by Esri. Use dark colors for code blocksCopy `1 "helpURL": "https://machine.domain.com/webadaptor/home/ClassificationToolHelp.pdf",`
`bannerExpression`		Generates the banner text for an item using Arcade expressions. After an item has been classified, the classification marking is stored as a JSON object on the item, which includes the banner text, and is returned as part of the item's details. Note that not every classification value needs to be part of an item's banner. Specified or assigned values that are not included as part of the banner text are still retained. If this property is not included in the schema, or its value is set to an empty string, generic encoding logic for the `uiElement`, `bannerOrder`, `bannerLabel`, `labelDelimiter`, `valueDelimiter`, and `attributeDelimiter` properties are used for the banner text. Warning If the `bannerExpression` property is not included in the schema, or if its value is left empty, at least one attribute must include the `bannerOrder` property for generic encoding logic to take effect. Use dark colors for code blocksCopy `1 "bannerExpression": "arcade expression()",`
`selectionTextExpression`		Generates the selection text using Arcade expressions. Selection text is displayed in the Current Selections portion of the classification form. If this property is not included in the schema, or its value is set to an empty string, generic encoding logic for the `uiElement`, `selectionDisplayOrder`, `selectionDisplayLabel`, `selectionDelimiter`, `labelDelimiter`, `valueDelimiter`, and `attributeDelimiter` properties are used for the selection text. Note that not every classification value displayed as the selection text will be a part of the item's banner. Specified or assigned values that are not included as part of an item's banner text are still retained. Warning If the `selectionTextExpression` property is not included in the schema, or if its value is left empty, at least one attribute must include the `selectionDisplayOrder` property for generic encoding logic to take effect. Use dark colors for code blocksCopy `1 "selectionTextExpression": "arcade expression()"`
`attributeCategories`		An array of attribute categories. Attributes assigned one of these categories for their `attributeCategory` property will be listed under a tab of the same name on the classification form (e.g. an attribute labeled "Declassification Date" that has the value of `Must Include` for its `attributeCategory` will have its corresponding input field listed under the Must Include tab on the classification form). Warning Do not use `Default` as the name for any attribute category as its reserved for attributes that do not have a value defined for the `attributeCategory` property. Use dark colors for code blocksCopy `1 "attributeCategories": ["Must Include", "Optional"]`

Classification Metadata

The schema's classification metadata defines the primary classification attribute for organization items, as well as defines the attribute's default value, lists all possible classification values, and how those values will appear when selected on the classification form. All properties described in this section are required.

The sample code below demonstrates how the classification metadata properties have been set up for a specific schema. This sample does not show the full classification schema, just the base properties that immediately precedes classificationMetadata, though only classificationMetadata is shown by default.

Expand
Use dark colors for code blocksCopy
  "classificationMetadata": {
    "primaryAttribute": "classification",
    "defaultValue": "Unclassified",
    "classificationValueProperties": [
      {
        "value": "Unclassified",
        "acronym": "Unclassified",
        "backgroundColor": "Grey",
        "textColor": "Black"
      },
Expand

The table below outlines the properties for classificationMetadata.

Property Required Description

Property	Required	Description
`primaryAttribute`		Specifies the attribute that will appear as the primary classification field on the classification form. Use dark colors for code blocksCopy `1 "primaryAttribute": "classification",`
`defaultValue`		Sets the default value for the for `primaryAttribute`. This is also the value that will be assigned to items by default if they have not yet been classified. Use dark colors for code blocksCopy `1 "defaultValue": "Unclassified",`
`classificationValueProperties`		An array of objects that define properties for each value `primaryAttribute` classification option. The list below identifies the possible properties that can be included in each object, as well as specifies which properties are required: `value`: Required. Specifies the classification option's label. `acronym`: Optional. Sets an acronym for the classification option. `textColor`: Optional. Sets the color for the classification option's label. If the option is selected, the label will appear in this color under Current Selections on the classification form. This property accepts RGB and HEX values, as well as predefined color names (i.e. `Red`). `backgroundColor`: Optional. Sets the color that highlights the classification option's label. If the option is selected, the label will be highlighted in the specified color under Current Selections on the classification form. This property accepts RGB and HEX values, as well as predefined color names (i.e. `Red`). Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 "classificationValueProperties": [ { "value": "Unclassified", "acronym": "Unclassified", "backgroundColor": "Grey", "textColor": "Black" }, { "value": "In-confidence", "acronym": "In-confidence", "backgroundColor": "Black", "textColor": "White" }, ... ]`

primaryAttribute

Specifies the attribute that will appear as the primary classification field on the classification form.

Use dark colors for code blocksCopy
"primaryAttribute": "classification",

defaultValue

Sets the default value for the for primaryAttribute. This is also the value that will be assigned to items by default if they have not yet been classified.

Use dark colors for code blocksCopy
"defaultValue": "Unclassified",

classificationValueProperties

An array of objects that define properties for each value primaryAttribute classification option. The list below identifies the possible properties that can be included in each object, as well as specifies which properties are required:

value: Required. Specifies the classification option's label.
acronym: Optional. Sets an acronym for the classification option.
textColor: Optional. Sets the color for the classification option's label. If the option is selected, the label will appear in this color under Current Selections on the classification form. This property accepts RGB and HEX values, as well as predefined color names (i.e. Red).
backgroundColor: Optional. Sets the color that highlights the classification option's label. If the option is selected, the label will be highlighted in the specified color under Current Selections on the classification form. This property accepts RGB and HEX values, as well as predefined color names (i.e. Red).

Use dark colors for code blocksCopy
  "classificationValueProperties": [
    {
      "value": "Unclassified",
      "acronym": "Unclassified",
      "backgroundColor": "Grey",
      "textColor": "Black"
    },
    {
      "value": "In-confidence",
      "acronym": "In-confidence",
      "backgroundColor": "Black",
      "textColor": "White"
    },
    ...
  ]

Attributes

Attributes correspond to both the classification marking an item receives and the input fields that are displayed on the classification form. The attributes object is a map that associates a key (the attribute name) with a series of values (the components that make up an attribute).

Each attribute has three required properties: a label that specifies the display text for the input field on the classification form, a type that determines what type of data the input field accepts, and a uiElement that the input field is displayed as on the classification form. Outside of these required properties are a number of optional properties that can set default values for an attribute or determine how an attribute and its selected values are stored on the item or displayed during classification.

The sample code below demonstrates how the attributes object has been set up for a specific schema. This sample does not show the full classification schema, just the base properties and classification metadata that immediately precede attributes, though only attributes is shown by default. To the right of the sample code is an image that shows how attributes and their properties inform how they are displayed as input fields on the classification form.

Expand
Use dark colors for code blocksCopy
  "attributes": {
    "classification": {
      "label": "Classification",
      "description": "Classification",
      "type": "string",
      "uiElement": "single-select",
      "validValues": [
        {
          "label": "Unclassified",
          "value": "Unclassified"
        },
        {
          "label": "In-confidence",
Expand

Attributes being displayed as input fields on the classification form. The values for those input fields become the classification labels that are stored on the item as banner text, currently being displayed as selection text under Current Selections.

The table below outlines the required and optional properties for attributes.

Property	Required	Description
`label`		Specifies the label of the attribute that will be used on the classification form. Use dark colors for code blocksCopy `1 "label": "Classification",`
`description`		Provides a description for the attribute. This value is used as placeholder text for `text` `uiElement` input fields on the classification form. Use dark colors for code blocksCopy `1 "description": "Classification",`
`type`		Identifies the attribute's data type. The supported data types are: `string`, `date`, `integer`, `float`, and `Boolean`. Use dark colors for code blocksCopy `1 "type": "string",`
`isRequired`		A Boolean value that specifies if the attribute is required, meaning that it must be filled out on the classification form. If this property is included in the JSON object, it cannot be defined as an empty string. Accepted values are `true` (required) or `false` (optional). Use dark colors for code blocksCopy `1 "isRequired": "true",`
`uiElement`		Determines how the attribute's input fields are displayed on the classification form. There are seven potential UI elements an attribute can be set as: `checkbox`: A check box. `date`: A date picker that allows for a date to be selected from the calendar in a `MM/DD/YYYY` format. `multi-select`: A menu that allows for multiple options to be selected. `multi-grouped-select`: A drop-down menu that allows individual options from groups of related options to be selected. The top-level grouping itself cannot be selected. `multi-grouped-select-nested`: A drop-down menu that allows the top-level grouping of related item, or individual options within that grouping, to be selected. `single-select`: A menu that allows for only a single option to be selected. `text`: A single-line text box. Use dark colors for code blocksCopy `1 "uiElement": "single-select",`
`defaultValue`		Sets a default value for the `uiElement` type. For example, the default value for `checkbox` would be a Boolean value (true or false). For `multi-select`, `multi-grouped-select`, `multi-grouped-select-nested`, and `single-select`, the default value would refelct an option or set of options from each menu. Use dark colors for code blocksCopy `1 "defaultValue": "Concealed",`
`defaultDateTimeline`		Sets a default value for attributes that have the `date` value set for `uiElement`. If this property is included, the `defaultDateTimelineUnits` property must also be set. Use dark colors for code blocksCopy `1 "defaultDateTimeline": 25,`
`defaultDateTimelineUnits`		Provides the units for the value set in the `defaultDateTimeline` property. The supported unit types are: `years`, `months`, and `days`. When combined with `defaultDateTimeline`, both properties set a default date for attributes that have the `date` value set for `uiElement`. Use dark colors for code blocksCopy `1 "defaultDateTimelineUnits": "years",`
`validValues`		An array that provides a list of options for attributes with either `multi-select` or `single-select` as the value for `uiElement`. This property should either be excluded or left empty if the list of values will instead come from the `validValuesMap` or `valueExpression` properties. Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 "validValues": [ { "label": "Unclassified", "value": "Unclassified" }, { "label": "In-confidence", "value": "In-confidence" }, { "label": "Sensitive", "value": "Sensitive" }, { "label": "Restricted", "value": "Restricted" }, { "label": "Confidential", "value": "Confidential" }, { "label": "Secret", "value": "Secret" }, { "label": "Top Secret", "value": "Top Secret" } ],`
`validValuesMap`		A map that defines the grouping of options for attributes with either `multi-grouped-select` or `multi-grouped-select-nested` as the value for `uiElement`. This property should either be excluded or left empty if the list of values will instead come from the `validValues` or `valueExpression` properties.
`valueExpression`		Defines a list of options for attributes using an Arcade expression. This property should be used if `validValues` or `validValuesMap` are not defined or are left empty.
`arcadeResultLookup`		A map of keys and values that allows the Arcade expression defined for `valueExpression` to generate a list of options.
`isAttributeEnabled`		Uses an Arcade expression that evaluates to a Boolean value that determines whether the attribute should be shown or hidden on the classification form.
`attributeValidation`		Uses an Arcade expression to either return an empty string or an error message when a value is selected for an attribute on the classification form.
`attributeCategory`		Designates which of the `attributeCategories` the attribute will appear under on the classification form. If the `attributeCategory` property is included, the value must specify one of the categories listed in the `attributeCategories` property. Use dark colors for code blocksCopy `1 "attributeCategory": "Must Include",`
`selectionDisplayOrder`		Specifies the order in which selected attributes appear in the Current Selections text on the classification form. The value specified for `selectionDisplayOrder` does not need to match the value set for `bannerOrder`. Warning At least one attribute must have a value set for `selectionDisplayOrder` if `selectionExpression` was not included (or was left empty) as one of the schema's base properties. Use dark colors for code blocksCopy `1 "selectionDisplayOrder": 3,`
`selectionDisplayLabel`		Specifies the label for an attribute when it appears in the Current Selections* text on the classification form. Use dark colors for code blocksCopy `1 "selectionDisplayLabel": "To be reviewed on",`
`bannerOrder`		Specifies the order in which attributes appear in the banner information stored on the item. The value specified for `bannerOrder` does not need to match the value set for `selectionDisplayOrder`. Warning At least one attribute must have a value set for `bannerOrder` if `bannerExpression` was not included (or was left empty) as one of the schema's base properties. Use dark colors for code blocksCopy `1 "bannerOrder": 6,`
`bannerLabel`		Specifies the label for the attribute when it appears in banner information stored on the item. Use dark colors for code blocksCopy `1 "bannerLabel": "To be reviewed on",`
`labelDelimiter`		Sets the delimiter between an attribute's label and value when it's displayed in the banner information and in the Current Selections text. Use dark colors for code blocksCopy `1 labelDelimiter": "-",`
`valueDelimiter`		Sets the delimiter between the multiple values for an attribute when it's displayed in the banner information and in the Current Selections text. This property applies to attributes that have either the `multi-select`, `multi-grouped-selected`, or `multi-grouped-select-nested` set as the value for `uiElement`. Use dark colors for code blocksCopy `1 "valueDelimiter": ",",`
`attributeDelimiter`		Sets the delimiter between each attribute listed in the banner information and in the Current Selections text. Use dark colors for code blocksCopy `1 "attributeDelimiter": "//"`
`labelTooltip`		Specifies the help text that is returned whenever a user hovers over the Information button next to an attribute on the classification form. Use dark colors for code blocksCopy `1 "labelTooltip": "Separete multiple entries by commas (,)."`

Layouts

The layouts object specifies the order of how the attributes are organized and displayed on the classification form. The layouts object is a series of nested objects:

default: An object that includes the details of a specific layout. This object contains the following sub-object:
- layoutElements: An object that maps each attribute to their placement on the classification form. This object contains a series of objects that each relate to the attributes defined in the schema:
  - attributeKey: The attributeKey value should be replaced with the name of an attribute. For example, if the schema includes the attribute declassifyDate, attributeKey would be changed to declassifyDate. Each attributeKey object must contain the following property:
    - formDisplayOrder: This property uses an integer value that specifies the numerlogical placement of the attribute on the classification form. For example, if an attributeKey object has its declassifyDate property set as 3, that attribute would appear as the third UI element on the classification form.

The sample code below demonstrates how the layouts object has been set up for a specific schema. Note that the attributeKey values have been replaced with the names of the attributes that have been defined in the schema. This code sample does include the full classification schema (base properties, classification metadata, attributes, and layouts), though only the layouts portion is shown by default.

It is important to note that the primaryAttribute will always be the first attribute displayed on the classification form.

Expand
Use dark colors for code blocksCopy
  "layouts": {
    "default": {
      "layoutElements": {
        "classification": {
          "formDisplayOrder": 1
        },
        "distribution": {
          "formDisplayOrder": 2
        },
        "reviewDate": {
          "formDisplayOrder": 3
        }
      }
    }
  }
}