Causes¶

Causes are accounts that produce messages that are intended to result in some sort of action taken by an 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?

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 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:

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.