summaryrefslogtreecommitdiffstats
path: root/toolkit/components/messaging-system/schemas/index.rst
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-19 00:47:55 +0000
commit26a029d407be480d791972afb5975cf62c9360a6 (patch)
treef435a8308119effd964b339f76abb83a57c29483 /toolkit/components/messaging-system/schemas/index.rst
parentInitial commit. (diff)
downloadfirefox-26a029d407be480d791972afb5975cf62c9360a6.tar.xz
firefox-26a029d407be480d791972afb5975cf62c9360a6.zip
Adding upstream version 124.0.1.upstream/124.0.1
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'toolkit/components/messaging-system/schemas/index.rst')
-rw-r--r--toolkit/components/messaging-system/schemas/index.rst186
1 files changed, 186 insertions, 0 deletions
diff --git a/toolkit/components/messaging-system/schemas/index.rst b/toolkit/components/messaging-system/schemas/index.rst
new file mode 100644
index 0000000000..f4db543600
--- /dev/null
+++ b/toolkit/components/messaging-system/schemas/index.rst
@@ -0,0 +1,186 @@
+Messaging System Schemas
+========================
+
+Docs
+----
+
+More information about `Messaging System`__.
+
+.. __: /browser/components/asrouter/docs
+
+Messages
+--------
+
+There are JSON schemas for each type of message that the Firefox Messaging
+System handles:
+
+* `CFR URLBar Chiclet <cfr_urlbar_chiclet_schema_>`_
+* `Extension Doorhanger <extension_doorhanger_schema_>`_
+* `Infobar <infobar_schema_>`_
+* `Spotlight <spotlight_schema_>`_
+* `Toast Notification <toast_notification_schema_>`_
+* `Toolbar Badge <toolbar_badge_schema_>`_
+* `Update Action <update_action_schema_>`_
+* `Whats New <whats_new_schema_>`_
+* `Private Browsing Newtab Promo Message <pbnewtab_promo_schema_>`_
+
+Together, they are combined into the `Messaging Experiments
+<messaging_experiments_schema_>`_ via a `script <make_schemas_script_>`_. This
+is the schema used for Nimbus experiments that target messaging features. All
+incoming messaging experiments will be validated against this schema.
+
+Schema Changes
+--------------
+
+To add a new message type to the Messaging Experiments schema:
+
+1. Add your message template schema.
+
+ Your message template schema only needs to define the following fields at a
+ minimum:
+
+ * ``template``: a string field that defines an identifier for your message.
+ This must be either a ``const`` or ``enum`` field.
+
+ For example, the ``template`` field of Spotlight looks like:
+
+ .. code-block:: json
+
+ { "type": "string", "const": "spotlight" }
+
+ * ``content``: an object field that defines your per-message unique content.
+
+ If your message requires ``targeting``, you must add a targeting field.
+
+ If your message supports triggering, there is a definition you can reference
+ the ``MessageTrigger`` `shared definition <Shared Definitions_>`_.
+
+ The ``groups``, ``frequency``, and ``priority`` fields will automatically be
+ inherited by your message.
+
+2. Ensure the schema has an ``$id`` member. This allows for references (e.g.,
+ ``{ "$ref": "#!/$defs/Foo" }``) to work in the bundled schema. See docs on
+ `bundling JSON schemas <jsonschema_bundling_>`_ for more information.
+
+3. Add the new schema to the list in `make-schemas.py <make_schemas_script_>`_.
+4. Build the new schema by running:
+
+ .. code-block:: shell
+
+ cd browser/components/asrouter/content-src/schemas/
+ ../../../../../mach python make-schemas.py
+
+5. Commit the results.
+
+Likewise, if you are modifying a message schema you must rebuild the generated
+schema:
+
+.. code-block:: shell
+
+ cd browser/components/asrouter/content-src/schemas/
+ ../../../../../mach python make-schemas.py
+
+If you do not, the `Firefox MS Schemas CI job <make_schemas_check_>`_ will fail.
+
+.. _run_make_schemas:
+
+You can run this locally via:
+
+.. code-block:: shell
+
+ cd browser/components/asrouter/content-src/schemas/
+ ../../../../../mach xpcshell extract-test-corpus.js
+ ../../../../../mach python make-schemas.py --check
+
+This test will re-generate the schema and compare it to
+``MessagingExperiment.schema.json``. If there is a difference, it will fail.
+The test will also validate the list of in-tree messages with the same schema
+validator that Experimenter uses to ensure that our schemas are compatible with
+Experimenter.
+
+Shared Definitions
+------------------
+
+Some definitions are shared across multiple schemas. Instead of copying and
+pasting the definitions between them and then having to manually keep them up to
+date, we keep them in a common schema that contains these defintitions:
+`FxMsCommon.schema.json <common_schema_>`_. Any definition that will be re-used
+across multiple schemas should be added to the common schema, which will have
+its definitions bundled into the generated schema. All references to the common
+schema will be rewritten in the generated schema.
+
+The definitions listed in this file are:
+
+* ``Message``, which defines the common fields present in each FxMS message;
+* ``MessageTrigger``, which defines a method that may trigger the message to be
+ presented to the user;
+* ``localizableText``, for when either a string or a string ID (for translation
+ purposes) can be used; and
+* ``localizedText``, for when a string ID is required.
+
+An example of using the ``localizableText`` definition in a message schema follows:
+
+.. code-block:: json
+
+ {
+ "type": "object",
+ "properties": {
+ "message": {
+ "$ref": "file:///FxMSCommon.schema.json#/$defs/localizableText"
+ "description": "The message as a string or string ID"
+ },
+ }
+ }
+
+
+Schema Tests
+------------
+
+We have in-tree tests (`Test_CFRMessageProvider`_,
+`Test_OnboardingMessageProvider`_, and `Test_PanelTestProvider`_), which
+validate existing messages with the generated schema.
+
+We also have compatibility tests for ensuring that our schemas work in
+`Experimenter`_. `Experimenter`_ uses a different JSON schema validation
+library, which is reused in the `Firefox MS Schemas CI job
+<make_schemas_check_>`_. This test validates a test corpus from
+`CFRMessageProvider`_, `OnboardingMessageProvider`_, and `PanelTestProvider`_
+with the same JSON schema validation library and configuration as Experimenter.
+
+See how to run these tests :ref:`above <run_make_schemas_>`.
+
+
+Triggers and actions
+---------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ SpecialMessageActionSchemas/index
+ TriggerActionSchemas/index
+
+.. _cfr_urlbar_chiclet_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/templates/CFR/templates/CFRUrlbarChiclet.schema.json
+.. _extension_doorhanger_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/templates/CFR/templates/ExtensionDoorhanger.schema.json
+.. _infobar_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/templates/CFR/templates/InfoBar.schema.json
+.. _spotlight_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/templates/OnboardingMessage/Spotlight.schema.json
+.. _toast_notification_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/templates/ToastNotification/ToastNotification.schema.json
+.. _toolbar_badge_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/templates/OnboardingMessage/ToolbarBadgeMessage.schema.json
+.. _update_action_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/templates/OnboardingMessage/UpdateAction.schema.json
+.. _whats_new_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/templates/OnboardingMessage/WhatsNewMessage.schema.json
+.. _protections_panel_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/templates/OnboardingMessage/ProtectionsPanelMessage.schema.json
+.. _pbnewtab_promo_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/templates/PBNewtab/NewtabPromoMessage.schema.json
+.. _messaging_experiments_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/schemas/MessagingExperiment.schema.json
+.. _common_schema: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/schemas/FxMSCommon.schema.json
+
+.. _make_schemas_script: https://searchfox.org/mozilla-central/source/browser/components/asrouter/content-src/schemas/make-schemas.py
+.. _jsonschema_bundling: https://json-schema.org/understanding-json-schema/structuring.html#bundling
+.. _make_schemas_check: https://searchfox.org/mozilla-central/source/taskcluster/ci/source-test/python.yml#425-438
+
+.. _Experimenter: https://experimenter.info
+
+.. _CFRMessageProvider: https://searchfox.org/mozilla-central/source/browser/components/asrouter/modules/CFRMessageProvider.jsm
+.. _PanelTestProvider: https://searchfox.org/mozilla-central/source/browser/components/asrouter/modules/PanelTestProvider.jsm
+.. _OnboardingMessageProvider: https://searchfox.org/mozilla-central/source/browser/components/asrouter/modules/OnboardingMessageProvider.sys.mjs
+.. _Test_CFRMessageProvider: https://searchfox.org/mozilla-central/source/browser/components/asrouter/tests//xpcshell/test_CFMessageProvider.js
+.. _Test_OnboardingMessageProvider: https://searchfox.org/mozilla-central/source/browser/components/asrouter/tests//xpcshell/test_OnboardingMessageProvider.js
+.. _Test_PanelTestProvider: https://searchfox.org/mozilla-central/source/browser/components/asrouter/tests//xpcshell/test_PanelTestProvider.js