realestatecore / rec Goto Github PK

Hi.

Is there any posibillity to get list of json examples?
I have looked at both code and doc, and found almost none.

Thanks.
Best regards
Bård Lind

This need has been brought up by several consortium members as well as external partners. We need a standardized way of connecting the building knowledge graph to external models/representation, where needed, such as CAD/BIM models, point clouds, etc. This may require some thinking and modeling prototypes, as well as further requirements elicitation from the partners in question.

In a similar way as an actuator and its actuation interface can express a payload data schema it'd be beneficial to express a similar reality for data residing in external systems (external to the REC platform implementation).

This requirement has emerged from work with WoT and Thing Descriptions

Proposed solution, preferably for 3.1.1

Introduce a new Software subclass DataInterface
Introduce a new object property hasDataInterface with domain Device and range DataInterface
Introduce a new object property dataSchema with domain DataInterface and range DataSchema

Note recommendation to anchor on Device, not Sensor.

Authentication and authorization is probably outside of scope of the API definitions themselves, but nonetheless, implementers will all need to built it -- so it would be useful if we provide some general recommendations on what works well and not.

At a dev workshop at Vasakronan on January 29, the tech team decided that the initial REC API will not mandate endpoints for every REC class. Instead, the classes which are required to exist as endpoints for compliance with the API spec shall be manually tagged using annotations in the ontology. We need to get these (MVP set from Idun), create a suitable annotation properyt ("RequiredApiEndpoint"/boolean?), and apply that property to the ontology classes in question.

At present, there are very few cardinality constraints on properties in REC. For generating an API and API documentation, a basic set of reasonable such constraints have been requested by developers (e.g., a sensor must have a mounting place of some sort, a building can (perhaps?) only be placed on one real estate, etc.).

Since adding such constraints enforce a more narrow semantics, this might formally be a breaking change. Will need to discuss the consequences within the consortium more extensively. One alternative might be to define a new optional "API Module" that the API is generated from, which extends but is not part of REC Full, and which adds said constraints. Another is to disregard that this is formally a breaking change and consider whether anyone would every have real data that would be invalidated by this update..

Metadata about certifications that some real estate have obtained: LEED, BREEAM, RESET, OVK, WELL, ...

Will not have full-blown representations of each of these certification models themselves (for that, refer to the respective certification).

But should include when the auditing took place, who carried it out, when certification will expire, etc etc.

Since #19 and #22 may require refactoring of how we think of observations/events, it makes sense to try and in this work also align REC to established work from SSN/SOSA, to the degree that this is possible/easy.

We need support for time intervals. Typically for aggregates (example total energy over January 2019, average daily temperature in building XYZ October 1-14 2019,...). The OWL Time ontology owl-time has this support and can likely be used directly or as inspiration.

Re-implement Premise as subclass of Collection. Re-implement PremisesType as previously designed.

For discussion at REC technical committee:

When we deprecated the Room subtypes, we did this for two reasons:

1. To generate a cleaner API w/o so many extra endpoints
2. To enable user customization of room types through the A-box (dataset), rather than require ontology modification

I would like to discuss whether these arguments still hold. For (1), our API generator can be set to include only a subset of classes (and is in fact set to do so for the official API), so having more classes will not create more endpoints. For (2), do our users actually do such customization, and if yes, is the availability of this design feature beneficial to them in that customization?

The arguments against this design are two:

A) Having two complementary typing methods (rdfs:subClassOf, rec:hasType) complicates translation of REC to other modeling languages.
B) Encouraging customization through A-box (dataset) modifications as opposed to ontology modification reduces incentive to participate in the REC community and bring your customizations to broader adoption

I'm in light of the above open to reverting this design, if the community and the tech committee agree. The same discussion also covers the premises types and device types.

This issue is open for any and all comments.

Once the API and/or API generator are stable enough, the OpenAPI specification document needs to be included with each REC release.

Based on discussions at workshop at VK 2019-10-18. Existing practices and models (SSN/SOSA etc) will need to be evaluated for reuse potential.

Rough outline:

Data is either
<- Raw data
<- "Generated data"

"Generated data" wasCreatedThroughProcess SomeProcessOrSoftware
SomeProcessOrSoftware wasFedBy SomeData
SomeProcessOrSoftware hadParameters SomeParameters (e.g., context, hardware, settings, etc)

"Generated data" can be connected directly to source sensors/buildings/placement context etc. through appropriate properties; but these can also be inferred by traversing the graph. How?

There's no inverse of object property associatedWithEvent:generatedObservation. Needed for returning Observation from API without returning the Device that generated the observation

We need to be able to represent things that are typically located inside real estate, but are not part_of that real estate. E.g., equipment, furniture, etc. Also need to find a good term for describing this concept. "Assets" has multiple connotations, some of which make it inappropriate in a real estate context.

Working on #18 we've found that the Leasable class is redundant. Conceptually, most things should be leasable but this will be modelled by extending the leaseOf property rather than an own named class.

Things like outdoor parking lots, bicycle parking, sheds, play grounds etc may need classes of their own!?

Could be RealEstateComponents or separate root class.

Akademiska Hus have expressed a need for annotating devices with geometries directly. The hasGeometry property from GeoSPARQL already allows for this (as it has no defined domain, it can be used on any class), but there is no hinting in the ontology that the API generator should include this property as an option for devices. Could be implemented by a restriction on devices, e.g., "hasGeometry max 1 Geometry", or "hasGeometry only Geometry". Can be implemented w/o extensive modelling/workshops.

Similar to the actuation interface that describes how to interact with an actuator there’s a need to be able to describe how to interact with a data platform. Basically defining the schema to be used in requests for a data series, the response format of data, and the URLs to request at. Such data interface may be used in connection with both “raw” as well as “constructed” data re workshop October 18 2019. And would typically be associated with a sensor or potentially a new Data class.

Bring presence semantics natively into REC. E.g., "How many people are in the conference room", "What is the typical utilization of the conference room", "Which paths do people typically take from room X to room Y", etc.

It is unclear to non-ontologists which effects the punning of RoomType and PremisesType instances entail. Describe this in a suitable place in the docs.

Inverse of "serves", indicating which devices that serve some building, buildingcomponent, device, etc.

A generic vocabulary for annotating REC objects with business data from other applications/systems, including some way of segmenting and grouping those annotations by system/namespace.

Not to be confused with OWL annotation properties.

We want to leave REC core as culture-agnostic as possible, but several partners have need of an (optional) module covering some Sweden-specific semantics. Those semantics include Lantmäteriets different data fields, e.g., fastighetsbeteckning (estate identifier), lägenhetsnummer (apartment number), Swedish street addresses and zip codes, etc.

Peter Hartlev will suggest some needed fields/values from Willhem's perspective and either develop a module, or deliver materials to Karl for implementation.

This module is not tied to or blocking a particular REC release on the roadmap, but we are looking at probably including it in the 3.1 or 3.2 release.

Entities sourced from existing systems may have multiple "aliases", i.e. identifiers that are unique for and derive from each source system, but that are not necessarily unique in the joint REC-formatted dataset. We need to be able to represent and query for such aliases, but also to ensure that they do not collide. Suggestion:

1. (for implementing systems) Mint new IRI:s for the aliases based on the source system(s), e.g., "http://ns.vasakronan.se/SomeLegacySystem#ABCD-1234".
2. (in the ontology, i.e., this issue ticket) Create an appropriate object property ("hasAlias?") for linking entities to such minted aliases. That property should be inverse functional, to indicate that no two entities may share aliases.

Should be extended to support RealEstate; BuildingStructure

From experience, the following extra individuals and classes are suggested to be added to REC class Room:
BankVault
DeliRoom
FoodStorageFreezerRoom
FoodStorageRefrigeratorRoom
FoodStorageRoom
StudyRoom
Vault

There's a need to be able to annotate devices with serial numbers to keep tally on the installed base. This may potentially be MAC addresses where such exist/are used as serial numbers or are part thereof => a MAC address property should probably be a sub property to S/N.

For the "best practices" folder?

Colons are disallowed in the component names. Concatenate qName into camel case instead?

In order to not break to much in deployment, postpone the naming changes (e.g., "hasValue" -> "value", "hasQuantityKind" -> "quantityKind") to version 4.0 instead, planned for the autumn.

Decision at workshop november 29: a base Collection class for the Core module (with object properties for linking members), and some foundational subclasses of that Collection class, complemented by an optional Collections module with more expressive collections types and relations (e.g., Lists).

In 3.1 the core:RelativeHumidity is of type core:MeasurementUnit, should be core:QuantityKind I believe

The "hasType" design pattern implemented in 3.1 for Rooms makes querying of underlying graph DB or triple store for the individuals much easier. Also it would be more homogenous to use the "hasType" pattern across the full ontology.

Recommended for 3.2. May be implemented similar to 3.1 where punning is used. The previous subclasses are deprecated but will remain at least until 4.0.

OWL -> SHACL validator? Relates to API issues. Will we, as consequence, define a REC Message Format?

Quality Assurance: ensure that

A) Equivalence assertions (i.e., for new analysis module) make sense and work in toolchain
B) Entities and Restrictions are defined in the same modules where they are used

Model external data sources.

1. Check overlap w/ Analytics module already in 3.2 dev branch.

@PeteHart will analyse and describe needs.

The Lease module is very rudimentary and needs enrichment including but not limited to:

• Customer, tenant, lease objects, premises - business focus
• Customer profiling
• Customer preferences

Typically conference rooms have a maximum occupancy, used for instance by booking systems. A data property for expressing this should be added to Room.

Note, may be relevant for other rooms than conference rooms, eg elevators, larger arenas due to fire regulations etc.

MQTT, Kafka, WebSockets, ...?

Supporting processes/analytics that understand and prioritize energy handling. E.g., "which machines are presently drawing power", or "How much power would be spent if we run all heating systems for X minutes". Need extensive support from Energy domain experts to implement.

For discussion in the REC technical committee:

We've presently copied a subset of the entities in QUDT (http://www.qudt.org/) into our quantity kinds and measurement units, grafted onto the REC namespace.

For alignment against other ontologies/systems, it would probably make sense if we could keep the canonical QUDT identifiers for the respective entities. If we want to guard against link rot we could redefine a known-good version of the QUDT entities within our own repo and serialized files (possibly as it's own module).

Encode the actually implemented actuation semantics from Idun and/or other REC platforms fully in the ontology, for a transparent and consistent semantics all the way through. If possible, also align with or reuse SOSA/SSN.

A request from Akademiska Hus, mirrored by @PeteHart: we need a way of representing room bookings in REC. Possibly the Lease semantics could be reused or extended. Approximate time-frame version 3.3, this autumn. A modeling workshop ought to include the above mentioned + any other interested stakeholders.

At the moment the linkage to QuantityKind and PlacementContext are in a sense redundant (linked from both events and devices, through subproperties). This is driven by early API needs, where requests for observations need to get this associated metadata as well. At workshop 2019-10-18 a consensus was reached on:

1. Removing the subproperties
2. Simplifying the naming of the remaining superproperties (removing "has")
3. Setting up scoped domains for the places in the model where they would typically be used (e.g. ,on Event and Device).

I.e., improve the quality of the tentatively designed BACNET, MODBUS, KNX, etc. classes, and also integrate w/ WoT Forms description and ideally other service descriptions also. We have data schemas defined in 3.2, now we need to express how to actually talk to the systems that use those schemas.

We need to make the Configuration-related aspects of device use more explicit. Includes things like correct (or allowed) configurations, vs incorrect (broken) configs, parameter sets, how to modify parameters, how to read parameters, etc. Closely aligned with #37

At present the semantics for the actuation and observation models are a little conceptually divergent. Configurations are not covered very well, and to the degree they are, are not aligned either. We'll probably need to harmonize this for usability's sake, down the line.