Add a new property to the keymasters for specifying XMPP jid.

The key name should xmpp or jid and the type should be a string.

We want to add the directory schema as well so we should move the endpoint schema in a folder.

Should we merge / close the open PRs first?

Most sensors have different intervals of providing their value (like every 5 minutes or once a day).
Sometimes a sensor is disconnected, say, shut down manually, wireless problems, crashed or for whatever reason inconclusive.
It would be handy to allow a lastchange field next to its value similar to the spacestate open value.

A sensor example would look as followed:

        "power_consumption": [
            {
                "value": 0,
                "unit": "W",
                "location": "hackspace",
                "lastchange": 1645017421,
                "name": "hackcorner",
                "description": ""
            }
        ],

The API docs for location/lon is:

Use positive values for locations west of Greenwich, and negative values for locations east of Greenwich.

It should be vice versa like +13.0° for eastern longitude.
Otherwise locations of FIXME and coredump could be wrong ;-)

Hi,

I propose to add a new top-level property called membership_fees. It should be an array with objects in it. The properties in the object should be:

• name
  • type: string
  • description: For example Student Membership, Normal Membership etc...
• value
  • type: number
  • description: How much does it cost!
• currency
  • type: string
  • description: In which currency is it
• renewal_interval
  • type: string with enum
  • description: How long does the membership last or when do you have to pay again
  • possible values: yearly, monthly, weekly, biyearly, semiyearly
• description
  • type: string
  • description: A free form string

Since #56 it is possible to provide a sort of compatibility indication server side, but there is no client side preferred version possible.

We're looking into migrating to newer SpaceAPI versions but our hackerspace makes heavily use of the null/undefined spacestate on the backend where it determines that after n minutes, there is no certain state (internet loss, power failure, building torn down).

We also have multiple implementations of several (embedded) clients that reflect the v.013 state, so upgrading to the future v0.15 would most likely break those implementations (of which one is built into a car dashboard).

What would your suggestion be for a client to indicate support for newer versions?
Can these suggestions be documented as well?

In my opinion there are a couple of ways to go about:

• look at the user agent requesting the API; very prone to errors
• provide a compatibility parameter, I.E. https://ackspace.nl/spaceAPI/?api_compatibility=13,14,15 (simple, but might not work for all implementations)
• provide a custom request header: X-API-Compatibility: (not recommended since custom X- prefixes are deprecated since 2012
• provide name value pair within the Accept header like described in RFC7231 section 5.3.2(fairly complex) for example, prefer version 15 but accept version 14 as well: Accept: application/json;api=14;q=0.1, application/json;api=15

API endpoints might default to their liking but still provide forward compatibility while clients can specify which version they actually want.

I know this could be regarded as an edge case, but it might assist in migrating to future versions really well where a hackerspace wants to provide the latest and greatest while still pleasing the dozens of IOT devices that might be difficult to upgrade.

In the space api version 0.13 the state is a required key. The value of state must be an object containing at least the open key. The open key is required but it's value is nullable.

In our space api endpoint at the ccczh [1] we have not (yet) implemented exposing the current state, this forces us to permanently set the open value to null.

If the state would not be required then intuitively I would say 'open': null means sensor data currently not available and the absence of a state key would mean that the state sensor never has been implemented for this space.

[1] https://www.ccczh.ch/api/v13/

All currency related properties should allow all ISO codes from ISO 4217 Official Spreadsheet

It only requires adding all the ISO codes to the enum.

This does currently only affect sensors.account_balance.

There are multiple references to the OpenSpaceLint repo.

The location.address field is described as "The postal address of your space (street, block, housenumber, zip code, city, whatever you usually need in your country, and the country itself).".

This could be interpreted as "the address of your space". But it could also mean "the address where you can receive mail". For example, for Coredump these two are different.

I would suggest the following to clarify this:

• Adjust the description of location.address from "The postal address of your space" to "The address of your space" to avoid confusion
• Add contact.postal_address string field with the following description: "The postal address of your space (street, block, housenumber, zip code, city, whatever you usually need in your country, and the country itself). May also be a post office box. This is where you can receive mail."

Opinions, @SpaceApi/core?

In v0.13 the state.open field was required but nullable. In v14 that was changed, the field is now optional but not nullable.

Unfortunately that means that it's not possible to have a v0.13+v14-compliant endpoint that sets the opening state to "undefined" 😕

Do we need to take action, or do we just live with that fact for now?

Remove he google plus section from contacts as the service no longer exists.

source: https://plus.google.com/

I would love to see the state of our 3D printers through the api,

not sure where exactly to put them in the json, though.

Could that be included?

New specification is out!

New version is 2019-09, you can find it here:
https://json-schema.org/specification.html

Current JSON Schema versions support examples for object definitions.

This could be used as an alternative or complement to the examples we currently use inlined in the description.

The docs generator could then render appropriate code blocks.

Right now feeds is an object with keys blog, wiki, calendar and flickr.

Issues with this:

• There is a mix between generic terms (like "wiki") and a service that seems a bit out-of-place ("flickr"). It would be good if the category would be free-form, but we could suggest a list of common keys (similar to OpenStreetMap).
• We cannot define multiple feeds of the same type (e.g. two calendar feeds). I'd suggest to change feeds from an object to a list of objects. Every feed object would then have the keys format (e.g. "rss" or "ical"), category (e.g. "wiki" or "radio_show"), description (e.g. "Our regular meetups at the hackerspace") and url.

This is a breaking change, so maybe it shouldn't be included in 0.14 yet.

Very similar to #50:

• There is a mix between stream formats (like "mjpeg") and a service that seems a bit out-of-place ("ustream"). Ustream is dead, by the way.
• Shouldn't m4 be mp4? How is this being used in practice?
• Only one stream can be defined per format, and there is no description. We should probably transition to a list of objects with a format key and a description field.

Somethings is wrong with our schema validation.

I've opened #73 and the schema validation went through, after squash merge it into b23285d it now reports error: Unexpected token ':' (regardless if --errors is set to json or text).

I get the same problem locally, but can't figure out whats wrong, the error message is very generic and i can't figure out a way to make the output more verbose.

Our schema and the downloaded draft-07 are both valid according to ECMA-404, RFC 4627, RFC 7159 and RFC 8259 (so i'm pretty sure there is no colon where it shouldn't be).

Error can be found here.

Some spaces occupy a room in a shared building and need a bit more details apart from the postal address or location in general (for example, vertical offset is currently not taken into account)

My suggestion would be to add the following two (optional) fields:

• floor: possibly integer; it might need consensus on how numbering is applied, i.e.: in most European countries we start counting at 0 (ground floor)
• room: string; a dedicated room "number" as provided by the building manager, in the case of ACKspace, it's L406 from wing/section "L", floor "4" and door "6" as provided per building.

An example would look like this:

    "location": {
        "address": "Kloosterweg 1, 6412 CN Heerlen",
        "lat": 50.8924622,
        "lon": 5.9712601,
        "timezone": "Europe/Amsterdam",
        "floor": 4,
        "room": "L406"
    },

Tracking issue for releasing 0.14 to the public.

Todos as discussed in the core meeting

• Add migration guide
• Explain how to be compatible with 0.13 and 0.14
• Cleanup CHANGELOG.md (#69)
• [na] Make the MyHackerspace app compatible (let's not delay the specs release with the app update)
• Take a look at open issues
  • #71 -> Postponed to v15
  • #58 -> replaced by #80

In there we could add things like:

• Summary: Describe the change?
• Rationale: Why is this change necessary? Why can't it be implemented with ext_ keys?
• Checklist: Schema file was updated, CHANGELOG was updated

In #106 we made the top-level location field optional. If it is defined, the lat/lon fields still need to be defined though.

Some virtual spaces might not have a location, but they might still have:

• A shared timezone (location.timezone)
• A shared country code (location.country_code, since #108)
• A postal address (location.address, although this is being discussed in #104)

Maybe we should make the location required again, but allow omitting all fields?

"location": {}

Alternatively, we could keep location as optional, but make location.lat and location.lon optional as well. (Potentially with some rules to say that if one of them is defined, the other one must be defined as well.)

Thoughts, @SpaceApi/core? This question is a release blocker for v15.

The nullability of state.open is documented as deprecated but I couldn't find the rationale. A nullable field is much easier to deal with when generating JSON, because the code for conditionally adding a key is much more involved than a simple ternary. The side that reads the JSON won't get much simpler for a non-nullable-but-optional field, as far as I can tell, especially considering backwards compatibility and considering that good programmers write defensive code that can deal with unexpected values, anyway.

Please reconsider whether state.open should indeed be non-nullable. I think it's better the way it is. Or if you must change this anyway, please provide why this change is actually beneficial.

I think it makes sense to keep space.open nullable, and to document that a null value or the lack of this value are to be considered equal, and that it is an indication of a temporary disruption in the availability of the space open state.

I would like to change state.lastchange type from number to date-time.

The problem lies within that a simple number does not carry timezone information with it. As there is no timezone field specified in the API, apps cannot determine in which timezone a space lives.

JSON Schema defines the date-time type, which is the rfc3339 format.

I think also that in future all time related properties should be date-time type, if there are added

Since we encountered annoying issues in v14 while implementing it in spaceapi-rs for example I think we should start implementing it at least once before the release.

• spaceapi-community/spaceapi-rs#118

For state.lastchange and events[ ].timestamp you are using Unix timestamps, but for radio_show[ ].start and radio_show[ ].end you are using strings in ISO 8601 format. I would appreciate to use a single time format for simplicity.

Hey,

Currently the spaceapi only supports one value for each contact item.

Wouldn't it be better to support multiple values. For examples a space might have multiple phone numbers or it might have multiple twitter/mastodon accounts.

Cheers,
metalgamer

Some dutch hackerspaces (Revspace, TkkrLab, Bitlair) have started providing their spacestate over MQTT, in addition to the spacestate in the spaceapi json file. The added value is that MQTT is push based instead of polling.

We've added the details of our MQTT spacestate service to the state object in the spaceapi json file as follows:

  "state": {
...
    "mqtt": {
      "host": "mqtt.tkkrlab.nl",
      "port": 1883,
      "tls": false,
      "topic": "tkkrlab/spacestate",
      "open": "1",
      "closed": "0"
    },
...
  }

The "mqtt" optional object contains the following required properties:

• "host": the hostname or IP address of the MQTT server (string)
• "port": the TCP port of the MQTT server (number)
• "tls": weither or not the MQTT server uses TLS encryption (boolean)
• "topic": the topic to subscribe to (string)
• "open": the message value published when the space is open (string)
• "closed": the message value published when the space is closed (string)

It would be extremely awesome if this addition could be added to the SpaceAPI json schema as an optional extra method for publishing the space state.

In my opinion, the API should be defined not only as a schema, but also as a RESTful service. I understand, that this would basically break the "single json file hosting" approach some spaces take, but maybe a flag could be introduced, if REST functionality is available or not.

If an application only cares about the state::open value, it is utter nonsense to poll the whole schema. My proposal is, that each root key should also be a GET endpoint that can be queried separately. So if you call https://space.tld/api/state, you should only get the state object, if that makes sense.

I am looking forward to hear the opinion of all of you on that matter.

The $id url of any schema is unreachable at the moment. Opening https://schema.spaceapi.io/13.json gives a ERR_SSL_PROTOCOL_ERROR, possibly because you redirect http to https, but the server does not speak SSL on this vhost.

See discussion at #15 (comment).

Please tag the source instead of adding a new file for a new version. This would make it much easier to see what was changed without using a diff tool.

Thanks

In v15, there should be a way to specify webcams with metadata (e.g. location, description, etc) similar to sensors.

Maybe we could add a new field (webcams? cams? cameras?) that replaces the cam field and is a list of objects?

Use case: We have a web cam connected to the 3D printer in our space (https://webcam.coredump.ch/, currently broken but will be fixed soon™), and would like to label it appropriately.

The unit for the "barometer" device is wrongly capitalized, it should be "hPa" instead of "hPA" (see https://en.wikipedia.org/wiki/Pascal_%28unit%29 )

Should we move this repository to the https://github.com/SpaceApi organization?
@dbrgn @gidsi @slopjong?

We could add a "mastodon" key to the contact section:

https://joinmastodon.org/

Any feedback?

Sometimes seeing the country code of a space might be useful. For example:

• Knowing in which part of the world a space is: "Garoa Hacker Clube" is loated at -23.564968, -46.69918. Quick, without entering the coordinates into a mapping system, where in the world is it? Coordinates are nice, but sometimes it would be useful to see right away that this space is located in Brazil.
• Namespacing: There are two spaces with similar name and you're not sure which is which, so by looking at the country code you immediately know which region they belong to
• Filtering: You'd like to know what other spaces there are in your country or in the country you're currently visiting. (Note: This can also be done based on distance using the coordinates, but it's more complex to calculate. The country definitely doesn't replace "spaces within 100km of you" though, especially when you live close to the boarder.)

Downsides:

• It's somewhat redundant information (but on the other hand lat/lon reverse lookup to find a country can be a bit complicated and requires an API or a big local geodatabase)
• Some people might object due to political reasons (since boarders and country names should not matter and are a sign of a nationalistic way of thinking which should be avoided?). I do not share that view though.

Any opinions on adding an optional ISO 3166 ALPHA-2 country code to the "location" field in the schema? Useful? Redundant and useless? A symptom of conservative nationalistic opressive patriarchy?