Add endpoind field to linked_spaces, rename url field to website

[renzenicolai]

By adding a field to specify the SpaceAPI endpoints of other spaces self discovery of the spaces in the SpaceAPI network becomes possible. This change would eventually allow for a SpaceAPI that is functional without the central directory.

If the endpoint field is filled out then the URL field of the linked space should be left absent as the url can instead be read from the spaces own SpaceAPI endpoint. Because of this I've made the URL endpoint optional.

[rnestler]

I remember discussing this as part of https://github.com/SpaceApi/schema/pull/75, but apparently not on the PR itself but somewhere else. As far as I remember @gidsi had some reasons not to use the SpaceAPI endpoint, but I can't recall them.

Edit: Found some stuff in the meeting notes:

• https://github.com/SpaceApi/meeting-notes/blob/master/20200809-telco.md#5-linked-spaces
• https://github.com/SpaceApi/meeting-notes/blob/master/20200510-telco.md#5-decentralized-directory

[gidsi]

The discussions are linked in the PR :)

I can write something about the "why" later

[s3lph]

@SpaceApi/core I think we should have another look at this PR:

• I agree that it would be beneficial if the SpaceAPI endpoints were all published at e.g. /.well-known/spaceapi.json. However, this is not the case currently, and even if we decided to go this way, it would take ages for all endpoints to migrate to the new path. Only linking to the base URL would make it impossible to link to spaces that have not migrated their endpoint to the new location.
• Implementing other mechanisms for SpaceAPI endpoint discovery would require much more complicated clients. For example, with the <meta name="spaceapi"> HTML tag proposed in #144, clients would suddenly need to parse HTML in addition to JSON.

If we decide to merge this PR, I'd even go so far as to make the endpoint field mandatory and remove the url field (at least for now), as it would not serve any purpose at the moment, and would probably create confusion.

[dbrgn]

I agree with @s3lph. I think we should stick to endpoint URLs for now. They are easy to understand, allow for easy redirecting, and don't require any additional parsing.

If we decide to support some .well-known/...-scheme, we can always add that later on.

[dbrgn]

Decision in today's SpaceAPI core meeting:

• Rename url to website
• Support both website and endpoint, with anyOf requirement (i.e. make none of them required)

[s3lph]

Hm unless I'm mistaken the "any of" requirement can't be modeled with JSONSchema. We could use minProperties: 1, but that would also pass validation if ONLY non-standard ext_ fields are provided. We could work around that with additionalProperties: false but that would prevent the use of ext_ fields entirely in this specific location.

[rnestler]

Hm unless I'm mistaken the "any of" requirement can't be modeled with JSONSchema.

Why not? Reading https://json-schema.org/understanding-json-schema/reference/combining#anyOf it looks like it should be possible.

[s3lph]

Huh... why is anyOf in the JSONSchema core spec, but required is in the validation spec? No wonder I didn't find it in the latter one.

So I guess we'd need to use something like this?

"linked_spaces": {
  "type": "array",
  "items": {
    "anyOf": [
      {
        "type": "object",
        "properties": {
          "endpoint": {
            "type": "string"
          }
        },
        "required": ["endpoint"]
      },
      {
        "type": "object",
        "properties": {
          "website": {
            "type": "string"
          }
        },
        "required": ["website"]
      }
    ]
  }
}

[rnestler]

To my understanding you can extract all commen things out of the anyOf and just keep the required in it.

[rnestler]

Rename url to website

Should we deprecate url first before removing it?

[dbrgn]

Rename url to website

Should we deprecate url first before removing it?

Why? The old field was never released, so we can change it freely 🙂

[rnestler]

Why? The old field was never released, so we can change it freely 🙂

Ah true :laughing: