fep

FEP-19b3: Specifying Properties of a Service

Summary

Actors of type Service are used in the Fediverse to represent automated process. In this FEP, we suggest some property values to use to convey further information about the underlying automated process and the responsible parties for the automated process.

Property Values

Property values can be attached to an actor to specify additional values. Using property values has two key advantage:

The official definition of PropertyValue can be found at PropertyValue - Schema.org Type. The section Examples of Property Value contains examples and further discussions on the usage of property value.

Suggested Property Values

The property values suggested here are meant to provide information to the users of the Fediverse. They are not meant to influence the behavior of Fediverse applications.

Source

This property value should provide a link to the source code, e.g.

{
  "type": "PropertyValue",
  "name": "Source",
  "value": "https://codeberg.org/helge/release_helper"
}

Author

The Author field would specify the author of the source linked in Source. The exact format of the value can be debated. Some possibilities

Support

If the author of the service is not the one running it, one needs to use an alternative field. We suggest using Support in this case.

Frequency

One can run services with a periodic trigger, e.g. cron. This indicates their frequency. Example:

{
  "type": "PropertyValue",
  "name": "Frequency",
  "value": "At 42 minutes past the hour"
}

ServiceType

Indicates the type of the service, e.g. Comment Tracking System, see FEP-136c. This should be primarily used for services that do more complicated processing, and link to documentation what the service does.

{
  "type": "PropertyValue",
  "name": "ServiceType",
  "value": "Comment Tracking System, https://bovine.codeberg.page/comments/136c/fep-136c/"
}

We imagine that specifying Reacts To Mentions would be useful to indicate that this is a bot the answers when mentioned. Furthermore, for bots just as @release, once might specify something like On Event, as they are triggered when continuous integration jobs are run.

Examples of property value

The following example is taken from the actor below

{
  "type": "PropertyValue",
  "name": "Source",
  "value": "https://codeberg.org/helge/release_helper"
}

In difference to the example provided by us, mastodon uses HTML as the value of property values, e.g.

{
  "type": "PropertyValue",
  "name": "🤖",
  "value": "<a href=\"https://botwiki.org\" target=\"_blank\" rel=\"nofollow noopener me\" translate=\"no\"><span class=\"invisible\">https://</span><span class=\"\">botwiki.org</span><span class=\"invisible\"></span></a>"
}

This example also shows another behavior, we recommend against: using emojis as name. This has the disadvantage of being awkward to parse (in particular for people using screen readers).

Example of actor with property value

An example of an actor with property values looks like

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    {
      "PropertyValue": {
        "@id": "https://schema.org/PropertyValue",
        "@context": {
          "value": "https://schema.org/value",
          "name": "https://schema.org/name"
        }
      }
    }
  ],
  "id": "https://dev.bovine.social/actor/kH3y9kw8cqRUgzso3oM3_w",
  "type": "Service",
  "preferredUsername": "release",
  "name": "release",
  "attachment": [
    {
      "type": "PropertyValue",
      "name": "Author",
      "value": "acct:helge@mymath.rocks"
    },
    {
      "type": "PropertyValue",
      "name": "Source",
      "value": "https://codeberg.org/helge/release_helper"
    }
  ], 
  "...": "..."
}

[!NOTE] There are variance with @context which change which URIs property values expand if one uses JSON-LD. As JSON-LD is unused for all practical purposes, this currently does not matter. See the Appendix for details on what goes wrong.

Appendix: The JSON-LD problem

The document

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    {
      "PropertyValue": {
        "@id": "https://schema.org/PropertyValue",
        "@context": {
          "value": "https://schema.org/value",
          "name": "https://schema.org/name"
        }
      }
    }
  ],
  "name": "release",
  "attachment": [
    {
      "type": "PropertyValue",
      "name": "Author",
      "value": "acct:helge@mymath.rocks"
    }
  ]
}

turns to

{
  "https://www.w3.org/ns/activitystreams#attachment": {
    "@type": "https://schema.org/PropertyValue",
    "https://schema.org/name": "Author",
    "https://schema.org/value": "acct:helge@mymath.rocks"
  },
  "https://www.w3.org/ns/activitystreams#name": "release"
}

when compacted against "@context": {}. Any variation of @context should behave similarly. The obvious choices

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://schema.org"
  ],
  "name": "release",
  "attachment": [
    {
      "type": "PropertyValue",
      "name": "Author",
      "value": "acct:helge@mymath.rocks"
    }
  ]
}

and with the order of "https://www.w3.org/ns/activitystreams" and "https://schema.org" reversed lead to incorrect results due to name being overloaded.

References

CC0 1.0 Universal (CC0 1.0) Public Domain Dedication

To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.