Property Flattening & Property Aliasing : RepreZen API Studio Community & Support

Start a new topic

Property Flattening & Property Aliasing

David Avendasora

started a topic about 2 years ago

The request:

In addition to RAPID-ML's `referenceEmbed` and `referenceLink`, I'd like to be able to `referenceFlatten`.

The example:

objectResource CompanyMinimalObject bound to type Company
    URI companies/{uuid}
    with only properties
        name
        responseFlatten > primaryPointOfContact
            targetProperties
                pocFirstName bound to property firstName
                pocLastName bound to property lastName
                pocTitle bound to property title

Which, in the case of JSON, would specify messages such as:

{
    "uuid": "a-uuid-here",
    "name": "Acme Anvils",
    "pocFirstName": "Road",
    "pocLastName": "Runner",
    "pocTitle": "Nemesis"
}

(notice I'm also proposing a way to rename/alias properties in the API)

Since the model knows what structure the "flattened" values came from and how they are mapped to its parameters, it should be possible to generate the required custom serializer/deserializer classes as well, in addition to the resource and model classes!

The need behind the request:

My organization is made up of several internal groups that all have, over the course of 30 years, developed their own "localized" version of enterprise-wide concepts. Each of these groups has cemented those variations in lots of legacy applications, databases and processes. There is no common naming convention for objects or attributes, let alone a common foundational structure.

We are in the process of unifying these systems, however we will rarely have the luxury of being able to dictate that all client applications change simultaneously to the new consistent, universal, naming conventions and structures.

RAPID-ML delivers on the promise of being able to easily and safely specify multiple representations of an object-graph. Yay!! But those representations can only vary in terms of including/excluding properties/structures. It can't vary the naming or modify the actual graph itself.

The philosophical implications:

These kinds of transformations abstract/break/denormalize/obfuscate/etc. the model from the message. If you are working on a new application with new clients and you want to flatten or alias properties, you should probably give the model some more thought.

With that said, legacy applications are a quagmire of conflicting naming and construction where flattening/aliasing are not just useful, but required.

I could see having a preference that enables flattening/aliasing and makes you agree to a stern talking-to about code clarity before you enable it.

1 Comment

Ted Epstein

said about 2 years ago

Dave,

Many thanks for providing the background and motivation. That's really helpful.

> My organization is made up of several internal groups that all have, over the course of 30 years,

> developed their own "localized" version of enterprise-wide concepts. Each of these groups has

> cemented those variations in lots of legacy applications, databases and processes. There is no

> common naming convention for objects or attributes, let alone a common foundational structure.

> We are in the process of unifying these systems, however we will rarely have the luxury of being

> able to dictate that all client applications change simultaneously to the new consistent, universal

> naming conventions and structures.

This sounds like a great example of bounded context. In Domain-Driven Design, a ubiquitous language exists within a certain organizational boundary, subject area, or system context. The vocabulary may be different outside that boundary.

DDD Also defines several patterns to describe the nature of team interactions and dependencies across contexts, and strategies for achieving (or not) certain levels of alignment and interoperability across contexts.

More sophisticated context-specific modeling and mapping is an area where we'd like to improve RAPID-ML. We've done some preliminary design thinking in this area, coming from a few different angles. Aliases came up in a discussion where the client had a need to expose different subsets of data, with different terminology, to different API consumers. Some design goals:

Allow definition of named contexts. (e.g. internal vs. external)
Data types and properties can have alternative names and documentation for different contexts.
Allow scoping of data structures and/or properties to specific contexts, filtered out of other contexts.
Allow named context to be specified in generation target configuration.

Here's an prototype of the new language features supporting this:

This is preliminary design thinking, by no means definitive. And as with most RAPID-ML features, building this out would happen in the context of a client engagement (or some other form of sponsorship).

Meanwhile, feel free to comment! We'd appreciate the feedback.

> RAPID-ML delivers on the promise of being able to easily and safely specify multiple representations

> of an object-graph. Yay!! But those representations can only vary in terms of including/excluding

> properties/structures. It can't vary the naming or modify the actual graph itself.

Just for the record, there are several other ways in which realizations can vary:

Perspective - RAPID-ML references can have an inverse attribute, which allows bi-directional navigation across an association between data structures. So, for example, you could have a 'Supplier' at the root of a message structure, with an embedded list of 'Products' underneath. Or you could do the opposite: list 'Product' at the root, with 'Suppliers' as the second level.
Linking and Embedding - RAPID-ML references can be realized as hyperlinks, embedded objects, or a combination of the two.
Contextual Constraints - Beyond the constraints specified in the underlying data model, individual resources and methods can layer on additional constraints in a property set. For example, a property that's optional in the data structure can be made required in the context of a particular resource, request or response. String properties can be further constrained to a fixed length, range of length, or regular expression, and numeric properties can have additional value range constraints within an API context.

None of this addresses your feature request, just providing this info here for people who are new to RAPID-ML.