src/chrome/common/extensions/docs/templates/articles/manifest/storage.html

   1 <h1>Manifest for storage areas</h1>
   2
   3 <p>
   4 Unlike the <code>local</code> and <code>sync</code> storage areas, the
   5 <code>managed</code> storage area requires its structure to be declared as
   6 <a href="http://tools.ietf.org/html/draft-zyp-json-schema-03">JSON Schema</a>
   7 and is strictly validated by Chrome. This schema must be stored in a file
   8 indicated by the <code>"managed_schema"</code> property of the
   9 <code>"storage"</code> manifest key and declares the enterprise
  10 policies supported by the {{platform}}.
  11 </p>
  12
  13 <p>
  14 Policies are analogous to options but are configured by a system
  15 administrator instead of the user, allowing the {{platform}} to be
  16 preconfigured for all users of an organization. See
  17 <a href="http://www.chromium.org/administrators/">how Chrome handles policies</a>
  18 for examples from Chrome itself.
  19 </p>
  20
  21 <p>
  22 After declaring the policies they can be read from the
  23 <a href="../storage.html#property-managed">storage.managed</a> API.
  24 It's up to the {{platform}} to enforce the policies configured
  25 by the administrator.
  26 </p>
  27
  28 <h2 id="manifest">Sample manifest.json</h2>
  29
  30 <p>
  31 The <code>storage.managed_schema</code> property indicates a file
  32 within the {{platform}} that contains the policy schema.
  33 </p>
  34
  35 <pre data-filename="manifest.json">
  36 {
  37   "name": "My enterprise {{platform}}",
  38   "storage": {
  39     "managed_schema": "schema.json"
  40   },
  41   ...
  42 }
  43 </pre>
  44
  45 <p>
  46 Chrome will then load these policies from the underlying operating system
  47 and from Google Apps for signed-in users. The
  48 <a href="../storage.html#event-onChanged">storage.onChanged</a>
  49 event is fired whenever a policy change is detected, including while
  50 the browser wasn't running if the {{platform}} uses
  51 <a href="../event_pages.html">event pages</a>.
  52 You can verify the policies that Chrome loaded at
  53 <a href="chrome://policy">chrome://policy</a>.
  54 </p>
  55
  56 <h2 id="format">Schema format</h2>
  57
  58 <p>
  59 The JSON Schema format has some additional requirements from Chrome:
  60 </p>
  61
  62 <ul>
  63 <li>The top-level schema must have type <code>object</code>.</li>
  64 <li>The top-level <code>object</code> can't have
  65 <code>additionalProperties</code>. The <code>properties</code>
  66 declared are the policies for this {{platform}}.</li>
  67 <li>Each schema must have either a <code>$ref</code> value or exactly one <code>type</code>.</li>
  68 </ul>
  69
  70 <p>
  71 If the schema is invalid then Chrome won't load the extension and will
  72 indicate the reason why the schema wasn't validated. If a policy value
  73 does not conform to the schema then it will not be published by the
  74 <code>storage.managed</code> API.
  75 </p>
  76
  77 <h2 id="sample">Sample schema</h2>
  78
  79 <pre data-filename="schema.json">
  80 {
  81   "type": "object",
  82
  83   // "properties" maps an optional key of this object to its schema. At the
  84   // top-level object, these keys are the policy names supported.
  85   "properties": {
  86
  87     // The policy name "AutoSave" is mapped to its schema, which in this case
  88     // declares it as a simple boolean value.
  89     // "title" and "description" are optional and are used to show a
  90     // user-friendly name and documentation to the administrator.
  91     "AutoSave": {
  92       "title": "Automatically save changes.",
  93       "description": "If set to true then changes will be automatically saved.",
  94       "type": "boolean"
  95     },
  96
  97     // Other simple types supported include "integer", "string" and "number".
  98     "PollRefreshRate": {
  99       "type": "integer"
 100     },
 101
 102     "DefaultServiceUrl": {
 103       "type": "string"
 104     },
 105
 106     // "array" is a list of items that conform to another schema, described
 107     // in "items". An example to this schema is [ "one", "two" ].
 108     "ServiceUrls": {
 109       "type": "array",
 110       "items": {
 111         "type": "string"
 112       }
 113     },
 114
 115     // A more complex example that describes a list of bookmarks. Each bookmark
 116     // has a "title", and can have a "url" or a list of "children" bookmarks.
 117     // The "id" attribute is used to name a schema, and other schemas can reuse
 118     // it using the "$ref" attribute.
 119     "Bookmarks": {
 120       "type": "array",
 121       "id": "ListOfBookmarks",
 122       "items": {
 123         "type": "object",
 124         "properties": {
 125           "title": { "type": "string" },
 126           "url": { "type": "string" },
 127           "children": { "$ref": "ListOfBookmarks" }
 128         }
 129       }
 130     },
 131
 132     // An "object" can have known properties listed as "properties", and can
 133     // optionally have "additionalProperties" indicating a schema to apply to
 134     // keys that aren't found in "properties".
 135     // This example policy could map a URL to its settings. An example value:
 136     // {
 137     //   "youtube.com": {
 138     //     "blacklisted": true
 139     //   },
 140     //   "google.com": {
 141     //     "bypass_proxy": true
 142     //   }
 143     // }
 144     "SettingsForUrls": {
 145       "type": "object",
 146       "additionalProperties": {
 147         "type": "object",
 148         "properties": {
 149           "blacklisted": { "type": "boolean" },
 150           "bypass_proxy": { "type": "boolean" }
 151         }
 152       }
 153     }
 154   }
 155 }
 156 </pre>