Policy schemas

Chrome policies are represented as policy schemas by the Schema Service API. Each policy schema has a unique name to identify it, a definition of setting fields and their types, and a human readable description of the settings in English.

For example, below is how the Schema Service API represents a setting that allows a sign out button to appear in Chrome's system tray. A simplified representation of this setting would be bool showLogoutButtonInTray. Click "Show an example" below to see how the Schema Service API represents this setting.

Show an example

{
  "name": "customers/C0202nabg/policySchemas/chrome.users.ShowLogoutButton",
  "policyDescription": "Show logout button in tray.", // description of the policy
  "definition": { // definition of the settings (fields names and types)
    "messageType": [
      {
        "name": "ShowLogoutButton",
        "field": [
          {
            "name": "showLogoutButtonInTray", // the setting showLogoutButtonInTray
            "number": 1,
            "label": "LABEL_OPTIONAL",
            "type": "TYPE_BOOL" // the setting showLogoutButtonInTray is of type boolean
          }
        ]
      }
    ]
  },
  "fieldDescriptions": [ // human readable descriptions of the settings and their values
    {
      "field": "showLogoutButtonInTray",
      "knownValueDescriptions": [
        {
          "value": "true",
          "description": "Show logout button in tray." // description for showLogoutButtonInTray=true
        },
        {
          "value": "false",
          "description": "Do not show logout button in tray." // description for showLogoutButtonInTray=false
        }
      ]
    }
  ],
  "schemaName": "chrome.users.ShowLogoutButton" //  unique name to identify the policy
}

Policy schema names

A schema's name is its unique identifier, with the following format: {namespace}.{leafName}.

In the example above, the full schema name is chrome.users.ShowLogoutButton. The namespace is chrome.users. and the leaf name is ShowLogoutButton.

Policies of similar scope are grouped under the same namespace. For example, all user policy schemas are prefixed with a chrome.users. namespace and all printer policy schemas are prefixed with a chrome.printers. namespace.

Namespaces

Namespace Key Required admin role permission
chrome.users.LEAF_NAME   Services > Chrome Management > Settings > Manage User Settings
chrome.users.apps.LEAF_NAME key="app_id" Services > Chrome Management > Settings > Manage User Settings > Manage Application Settings
chrome.users.appsconfig.LEAF_NAME   Services > Chrome Management > Settings > Manage User Settings > Manage Application Settings
chrome.devices.LEAF_NAME   Services > Chrome Management > Settings > Manage ChromeOS Device Settings
chrome.devices.managedguest.LEAF_NAME   Services > Chrome Management > Settings > Manage ChromeOS Device Settings
chrome.devices.managedguest.apps.LEAF_NAME key="app_id" Services > Chrome Management > Settings > Manage ChromeOS Device Settings
chrome.devices.kiosk.LEAF_NAME   Services > Chrome Management > Settings > Manage ChromeOS Device Settings
chrome.devices.kiosk.apps.LEAF_NAME key="app_id" Services > Chrome Management > Settings > Manage ChromeOS Device Settings
chrome.devices.kiosk.appsconfig.LEAF_NAME key="app_id" Services > Chrome Management > Settings > Manage ChromeOS Device Settings
chrome.printers.LEAF_NAME key="printer_id" Services > Chrome Management > Settings > Manage Printers
chrome.printservers.LEAF_NAME key="print_server_id" Services > Chrome Management > Settings > Manage Printers
chrome.networks.globalsettings.LEAF_NAME   Services > Shared Device Settings
chrome.networks.wifi.LEAF_NAME key="network_id" Services > Shared Device Settings
chrome.networks.ethernet.LEAF_NAME key="network_id" Services > Shared Device Settings
chrome.networks.vpn.LEAF_NAME key="network_id" Services > Shared Device Settings
chrome.networks.certificates.LEAF_NAME key="network_id" Services > Shared Device Settings

Policy schema keys

Some policies require additional context to be viewed or modified. For example:

  • To modify policy for an application, you need to specify which application by populating key="app_id".
  • To modify policy for printer settings in an Organizational Unit, you need to specify which printer by populating key="printer_id".

These policy schemas contain a additionalTargetKeyNames section that describes the keys and values to be passed in your API requests.

For more details, go to Code samples.

Show an example

{
  "name": "customers/C0202nabg/policySchemas/chrome.printers.AllowForUsers",
  "policyDescription": "Allows a printer for users in a given organization.",
  "additionalTargetKeyNames": [
    {
      "key": "printer_id",
      "keyDescription": "Id of printer as visible in Admin SDK printers API."
    }
  ],
  "definition": {
    "messageType": [
      {
        "name": "AllowForUsers",
        "field": [
          {
            "name": "allowForUsers",
            "number": 1,
            "label": "LABEL_OPTIONAL",
            "type": "TYPE_BOOL"
          }
        ]
      }
    ]
  },
  "fieldDescriptions": [
    {
      "field": "allowForUsers",
      "description": "Controls whether a printer is allowed for users in a given organization."
    }
  ],
  "schemaName": "chrome.printers.AllowForUsers"
}

App policies

Some of the namespaces above are for app policy, like User Apps, Kiosk Apps, Managed Guest Session Apps, and Kiosk Apps Config policies. App policies require an app_id.

An app_id is formed by combining the app type and app identifier. For example:

  • chrome:mkaakpdehdafacodkgkpghoibnmamcme represents the "Google Drawings" Chrome App
  • android:com.google.android.calendar represents the "Google Calendar" Android app
  • web:https://canvas.apps.chrome represents the "Canvas" Web app

Multi-value fields

Fields with the LABEL_REPEATED label represent multi-value fields, like lists or arrays. You can give several values to these fields. For more details, see the Code samples.

Policy schema status

Every policy has a policyApiLifecycle object to represent its current status. This object contains the following fields with details about the policy's status:

  • The policyApiLifecycleStage field shows which of the stages in the following table best describes the current status of the policy.
  • The description field gives more detail about this policy's current status.
  • The endSupport field shows the final supporting date for the policy, if one is defined.
  • The deprecatedInFavorOf can only be set if policyApiLifecycleStage is API_DEPRECATED. It shows the fully qualified namespace(s) of the new policies that current policy is deprecated in favor of.
  • The scheduledToDeprecatePolicies field is corresponding to deprecatedInFavorOf. It shows the fully qualified namespace(s) of the old policies that will be deprecated because of the introduction of this policy.

Lifecycle stages

Stage Description
API_UNSPECIFIED Policy's current status is unknown. Reserved, don't use.
API_PREVIEW Policy is not working yet. This stage can transfer to API_CURRENT or API_DEVELOPMENT.
API_DEVELOPMENT Policy is not finalized yet and breaking changes may be introduced. This stage can transfer to API_CURRENT or API_DEPRECATED.
API_CURRENT Policy is in an official format, but non-breaking change may be introduced. This stage can transfer to API_DEPRECATED.
API_DEPRECATED This policy is deprecated and might be removed in the future. Admins should stop using this policy.

Show an example

{
  "name": "customers/C0202nabg/policySchemas/chrome.users.OutdatedPolicy",
  "policyDescription": "Just for demo, this is an outdated policy.",
  "definition": {
    "messageType": [
      {
        "name": "OutdatedPolicy",
        "field": [
          {
            "name": "outdatedField",
            "number": 1,
            "label": "LABEL_OPTIONAL",
            "type": "TYPE_BOOL"
          }
        ]
      }
    ]
  },
  "fieldDescriptions": [
    {
      "field": "outdatedField",
      "description": "This is an outdated field"
    }
  ],
  "schemaName": "chrome.users.OutdatedPolicy",
  "policyApiLifecycle": { // policy's current lifecycle status
    "policyApiLifecycleStage": "API_DEPRECATED",
    "description": "This policy is deprecated. Please stop using it",
    "endSupport": {
      "year": 2021,
      "month": 2,
      "day": 29
    }
    "deprecatedInFavorOf": "chrome.users.NewPolicy"
  }
}

{
  "name": "customers/C0202nabg/policySchemas/chrome.users.NewPolicy",
  "policyDescription": "Just for demo, this is a new policy.",
  "definition": {
    "messageType": [
      {
        "name": "NewPolicy",
        "field": [
          {
            "name": "newField",
            "number": 1,
            "label": "LABEL_OPTIONAL",
            "type": "TYPE_BOOL"
          }
        ]
      }
    ]
  },
  "fieldDescriptions": [
    {
      "field": "newField",
      "description": "This is an new field"
    }
  ],
  "schemaName": "chrome.users.NewPolicy",
  "policyApiLifecycle": { // policy's current lifecycle status
    "policyApiLifecycleStage": "API_CURRENT,
    "scheduledToDeprecatePolicies": "chrome.users.OutdatedPolicy"
  }
}

Policy schema notices

Some policies have notices associated with them that have acknowledgement_required set to true for certain values of certain policy fields. For these policies, you need to set a special acknowledgement field to true before you can set the value.

For more details, see Code samples.

Supported platforms

supportedPlatforms is a list which indicates that the policy will only apply to devices or users on these platforms. All supported platforms are listed in the following table.

Supported platform

Platform Description
PLATFORM_UNSPECIFIED Unspecified platform. Reserved, don't use.
CHROME_OS ChromeOS
CHROME_BROWSER Chrome Browser for macOS/Windows/Linux
CHROME_BROWSER_FOR_ANDROID Chrome Browser for Android
CHROME_BROWSER_FOR_IOS Chrome Browser for iOS

Next steps