Hi folks, Following JB's suggestion, I'd like to start a dedicated discussion on the REST API payload representation for semantic models.
I think there are three possible approaches: 1. Represent the semantic model as a raw string. 2. Represent the semantic model as an opaque JSON document. 3. Model the semantic model structure directly in the REST specification. I think it's helpful to separate the REST API from Polaris' internal representation. The REST API is the long-term contract with clients, while the internal representation can evolve independently. I'm comfortable with either option 1 or option 2. Both avoid coupling the REST API to the Ossie schema and allow Polaris to validate the payload based on the semantic model type and version while preserving the document through write and read operations. My concern is with option 3. Since the Ossie schema is versioned and expected to evolve, modeling the full semantic model structure directly in the REST specification would tightly couple the Polaris REST API to Ossie versions. Every Ossie schema evolution could require changes to the REST specification, generated clients, and potentially client applications. Between options 1 and 2, I think there is an additional tradeoff. An opaque JSON document assumes that semantic models are always represented as JSON. While that works well for Ossie today, Polaris may support other semantic model formats in the future. For example, OKF[1] is defined as Markdown rather than JSON. Using a raw string keeps the REST API independent of any particular document format, allowing Polaris to support JSON, Markdown, or other representations without changing the API contract. So my current view is: - Option 1 provides the greatest flexibility and is format agnostic. - Option 2 is a natural choice if we want to optimize specifically for JSON based semantic models. - Option 3 provides strong typing, but at the cost of coupling the REST API to Ossie schema evolution. I'm happy with either option 1 or option 2, but I'd avoid option 3 for the reasons above. Thoughts? 1. https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing Thanks, Yufei
