[Specification] CDSC-WG1-01 - Server Metadata

[daniel-utilityapi]

This is the initial draft of a proposed specification for utility servers to publish metadata about their details and capabilities.

Relevant Issue: https://github.com/carbon-data-specification/Customer-Data/issues/15

NOTE: This is a draft in progress (see "TODO" throughout the draft) and will continue to be developed and modified based on feedback and comments in this pull request and during meetings

See a rendered preview of this specification on the maintainer's branch: https://daniel-utilityapi.github.io/Customer-Data/specs/cdsc-wg1-01

Timeline

This specification is under active development, so it will be merged when complete and reaching consensus among working group participants.

[eloifabrega]

Hello!

I was reviewing this and overall looks good to me. Nevertheless, I have a couple of comments:

• Would it be useful to specify here more characteristics of ¨commodity_type¨ data? Specifically for electricity, which data does the server offer or can be accessed? Billing, interval? Production, consumption? Maybe then they will not have to check the documentation linked for a specific utility, and this could be crucial for some Energy Service Providers that need to access more granular data for example.

• Also adding in server capabilities, might be useful (for an extended specifications phase) to add if the server allows access to third parties (and potential costs for that). Unless I miss it, this could only be checked in the ¨documentation¨ and from my experience, is not always easy to find from the potential servers (utilities).

Hope this can help and I am happy to discuss this all together! Many thanks :)

[greg-flexidao]

Hi All, Sorry I didn't yet check in depth the rest of the spec, my initial suggestions would be:

• Consider date-time format according to RFC-3339 in order to explicitly define the time of the event/period. The example in the specification provides explicit time (ISO8601), note that it is also RFC-3339 compliant. ISO unfortunately also allows for ambiguous datetimes that are one of the main plagues and source of issues in the industry. See https://ijmacd.github.io/rfc3339-iso8601/ for comparison.
• I would say that the endpoint/api should in general follow REST API principles. Unfortunately there is no ultimate source of truth for standard REST APIs (that I know of), here is however a comprehensive guide that could be followed and it can be referenced in the standard, that also includes the cases that have been mentioned. https://restfulapi.net/

Happy to participate in further spec development!