(cause)= # Causes Causes are accounts that produce messages that are intended to result in some sort of action taken by an {ref}`effect `. Messages can take any form that is valid as a Matrix message. In order to allow users to view the events, the messages can be `m.room.message` messages with a human-readable representation in the `body` property (and optionally the `formatted_body` property). In order to allow effects to parse the message more easily, the message should also contain structured data depending on what type of event it is representing. ## Version control Messages may be sent to indicate that something has happened in a version control repository. ### Commits Messages that indicate that something has been committed to the repository should include a `ca.uhoreg.merovingian.vcs` property with the following keys: - `type` (required): must be `commit`. - `vcs` (required): the version control system used. - `repository` (required): the location of the version control repository. - `branch` (optional): the name of the branch that the commit was made to. - `id` (required): an identifier for the commit. - `author` (required): the person who wrote the commit. This is an object with the following properties: - `name` (required): the author's name. - `email` (optional): the author's email address. - `committer` (optional): the person who committed to the repository. This is an object with the following properties: - `name` (required): the committer's name. - `email` (optional): the committer's email address. - `timestamp` (optional): the time when the commit was made as a UNIX timestamp in seconds. - `message` (optional): the commit message. - `detail` (optional): the detailed commit message. ### Tags/Branches Messages that indicate that a new tag or branch has been created in the repository should include a `ca.uhoreg.merovingian.vcs` property with the following keys: - `type` (required): must be `tag` or `commit`. - `repository` (required): the location of the version control repository. - `name` (required): the name of the tag/branch that was created. - `id` (required for tags): an identifier for the commit that the tag is on. ## Online resources Messages may be sent to indicate activity related to an online resource such as a web page. These resources can be described with RDF data, which can be embedded in the message using a `ca.uhoreg.merovingian.rdf` property that has the following properties: - `@id`: the identifier for the resource. This will often be the resource's URL - `@type` (optional): the type of object being described, including the vocabulary. - a property for each vocabulary that is used to describe the resource. The value is an object mapping property names (not including the vocabulary) to values. If a value is another resource or entity, it may be represented as another object of similar form to the top-level `ca.uhoreg.merovingian.rdf` property. Some RDF vocabularies are: - `http://purl.org/dc/elements/1.1/`: Dublin Core elements - `http://ogp.me/ns#`: Open Graph protocol, - `http://usefulinc.com/ns/doap#`: Description of a Project - `http://schema.org/`: schema.org FIXME: how do we do arrays and sub-properties? FIXME: how do we handle different data types? ```{code-block} json --- caption: example resource description --- { "ca.uhoreg.merovingian.rdf": { "@id": "https://merovingian.uhoreg.ca/", "@type": "http://schema.org/WebSite", "http://purl.org/dc/elements/1.1/": { "title": "Merovingian", "creator": "Hubert Chathi", "description": "A protocol for connecting bots together in Matrix.org" }, "http://ogp.me/ns#": { "type": "website", "title": "Merovingian", "url": "https://merovingian.uhoreg.ca/", "description": "A protocol for connecting bots together in Matrix.org" }, "http://schema.org/": { "headline": "Merovingian", "alternativeHeadline": "Exploiting cause and effect in matrix.org", "abstract": "A protocol for connecting bots together in Matrix.org", "url": "https://merovingian.uhoreg.ca/", "author": { "@id": "https://matrix.to/#/@hubert:uhoreg.ca", "@type": "http://schema.org/Person", "http://schema.org/": { "name": "Hubert Chathi" } }, "discussionUrl": "https://matrix.to/#/#le_vrai:uhoreg.ca", "license": "https://www.apache.org/licenses/LICENSE-2.0" } } } ``` Note that including multiple vocabularies may result in duplication of information. The example above is for illustration purposes only. ## Location data Messages that are related to a geographical location should include a `ca.uhoreg.merovingian.geo` property that is a [GeoJSON](https://geojson.org) object. ## Measurement data Messages that indicate some sort of measurement should include a `ca.uhoreg.merovingian.measurement` property with a property for each measurement. The value of the measurement should have a property for each unit of measure, whose value is the measurement value. To avoid issues with floating point numbers, numbers may be represented as strings. For example: ```{code-block} json --- caption: example weather measurement --- { "ca.uhoreg.merovingian.measurement": { "temperature": { "celcius": 0, "fahrenheit": 32 }, "humidity": { "percent": 70 }, "pressure": { "kpa": "101.3", "mmHg": 760, "inHg": "29.9" } } } ``` Periodic events --------------- Messages should include a `ca.uhoreg.merovingian.cron` property with the following keys: - `time` (required): the time (UTC) when the event was triggered. This is an object with the following properties: - `year` - `month` - `day` - `hour` - `minute` - `second` - `time-[tzname]` (optional): the time in a given time zone when the event was triggered. This uses the same properties as the `time` property. May be repeated multiple times for different time zones. `[tzname]` is arbitrary, but generally should be a name from the IANA time zone database. For example: ```{code-block} json { "ca.uhoreg.merovingian.cron": { "time": { "year": 2021, "month": 4, "day": 1, "hour": 0, "minute": 0, "second": 0 }, "time-America/Toronto": { "year": 2021, "month": 3, "day": 31, "hour": 19, "minute": 0, "second": 0 } } } ```