2022-03-29 Architecture Meeting Minutes

Public Page

Date: Mar 29, 2022

Agenda

• Antitrust

• Committee Welcome

• Meeting Minutes Review

• 2022R1 QA is Scheduled for Next Week, April 5

• Analyse approaches for Resource building Proof of Concepts (Please see Action Items Below)

  • POC for using $Ref to reference the objects

  • POC for creating common aggregate objects

Meeting Minutes

• Antitrust Accepted

• Welcome

  • Brief reminder that we added a few minutes to each meeting to introduce new people to the group or to allow current members to network.

  • Dan Webster updated the committee by letting them know Mitchell is working on Version 2 of the Assignment message. Version 2 is using JSON and the concepts that was started with CAPIS a year ago.

• Meeting Minutes Review

  • Reviewed Meeting minutes, made a few revisions.

  • Accepted Meeting minutes

  • Next week is 2022R1 QA

  • Dan and Mike both completed the homework they had from the previous meeting.

    • Mike Provided the Excel Documents he shared with the group last week

    • Dan provided the documents for POC using references and they were added to GitHub

  • GitHub Documents

    • In looking at the work provided; it appears that Dan and Mike are both using the same vehicleCommonAggregatesScheama.json that is located in GitHub CAPIS/Json-schema/vehicleCommonAggregatesSchema.json.

  • Excel Document

    • OdometerInfo is the aggregate that we were using to show how different applications would use this data different. The OdometerReading is the only required field in the Aggregate. The optional fields could be used different within the applications.

      • Column A shows the Flattening and Colum F shows the object

        • Looks like Column A was not updated to show the hierarchy that was added to the vehicleCommonAggregatesSchema.json

        • Since Odometer is not in the schema, it cannot be used to reference the excel

    • OdometerInfo as an example.

      • The OdometerInfo can be completely flattened in Vehicle and just one individual field of OdometerReading.

      • The next application that wants to reference OdometerReading also wants the OdometerMeasure and other fields in the OdometerInfo.

        • For this Example we are showing Vehicle completely flattened with no way to retrieve those fields without including Vehicle.

        • For Parts that wants to use OdometerReading and OdometerIndicator

        • Are we saying we don’t care about duplicating the field values of OdometerReading and OdometerIndicator in Parts because we no longer have an OdometerInfo Object?

    • Bundling is to allow you to have big external files with 100s of code list and dozens of aggregates in it. The Codes and aggregates used are in the primary schema, the budling goes and copies those from there. This is similar to Include files, where the bundling tule copies from the primary file into a single schema instead of a bunch of schemas as we did in XML. Bundling is not what we are talking about here, but instead referencing.

    • Today’s discussion seems to be about instances and not schemas. If the instance of a OdometerInfo is tow tiers with OdometerReading as an aggregate and OdometerReading as an element under it, or whether we just flatten that in, promote the children up instead of the parent.

    • The hierarchy is not as important as making sure we only have one definition.

      • The license plate number definition, whether you reference its parent and bring them all in at once or reference its property. Means we only have it defined once.

    • Column A is a straw man showing how you could completely flatten an object and was used as a starting point. After discussing it for several months, it is concluded that straw man has been rejected at this point.

      • Column A is very similar to EMS, which has worked for over 20 years. The problem is we didn't' have 118 properties, we only had 28 in the EMS. The complication with column A is we have a lot of properties that are probably never used and need to be removed from the schema.

      • With object hierarchy added it is easier to read and the main advantage is when we convert the schema into source code it will create objects in the source code. This is something that is real important to developers.

    • The Excel has Odometer as the name of the Agreggate instead of OdometerInfo. This is a typo that needs to be corrected.

    • The naming of VehicleDesc is not valid

      • Most fields in the BMS that have Desc in the name is a single field to describe the field. Therefore and aggregate being named anything with Desc is not a practice we want to follow.

      • LienHolderInd and KeysAvaialbeInd; don’t see how KeysAvaliableInd needs to be with make model

  • It was discovered that structuring schemas using what are called schema composition, the all of , the any of and the not, the tools will not produce source code. You have to have objects and properties in the root schema for the tools to generate source code. This is not just StopLight Studio but other tools used to convert into java code. It does seem to work in XML spy but none of the other tools.

    • If you don’t have an actual entity in the schema, if all it is has is references to other things, it does not actually validate anything. Its more like a catalog of things to be referenced by something else.

    • Each one of these JSON schemas has to declare some sort of a type, whether it’s an object or if there is no type and just a definitions section. Without objects, it doesn’t actually declare a schema that itself can be used to validate instances.

    • Like the flexibility of Referencing.

  • Look at example of data such as License Plate Number, is that field truly unique or does it need another field to make it unique?

    • In this case you would have to have 2 properties to have a valid license plate.

      • Body Shop having in the lot would be okay with a plate number, the system may have the state and number, but the human is only going to look at the plate number.

    • To make sure a license is still valid, we would need Expiration Date.

    • Odometer is another example of needing more than one property to make it valid.

      • Odometer would need unit of measure to make it useful.

    • System design is what we need to focus on for our standards. Developing standards where systems interface and fundamentally creating ambiguity. We are creating interfaces between systems and not people, so a best practice to drive out that ambiguity for the system and in the examples we know we already have aggregates that bring out that ambiguity and we should leverage that.

      • To further clarify, These are interfaces between systems and what gets displayed. What's made available in a shop management system is completely separate. You know, it may have all sorts of fields had hundreds of fields, and what it chooses to make readily available is really a separate discussion.

    • Using the BMS rule of 7 + or - 2. We can’t have an aggregate for more than 11 elements. When we got a 12 element, we added a level of hierarchy.

      • Object oriented would mean we would to it by resource object and not how many properties and sub grouped as it makes sense.

      • The flattening and the notion of flattening and how flat should it be or how much structure should there be in the object keeps coming up. CIECA needs to document what we want to say as an organization that makes sense. The discussions of sometimes they can be flat and sometimes they cannot be flat, then the area where we have 2 elements that must be grouped together. But as a committee, we can come up with a set of best practices about when it makes sense. So like if you have a vehicle and the vehicle has 100 different properties, some of those things may be grouped together, such as a license plate, or the odometer; so we group things where it makes sense.

      • We know any engineer that’s looking at the Best Practices Document is going to have some sort of knowledge about what's going to have to be in the schema at a minimum and hopefully this document like the BMS is able to be used as a reference to these things and instruct on what each of the fields mean.

      • We as a committee get to a place where we can describe what it means to be flattened or, work with minimized terms of not having extraneous layers in the schema.

      • Proposed Best Practice is when we have a property that need to go together they should be an Object and introduce a level of hierarchy.

      • Proposed Best Practice/Rule/Guiding Principal is no extraneous layers, layers that don't add value to the thing being transmitted or instance schema. For an example the OrgInfo or Party Aggregates in the BMS.

  • Arrays

    • Arrays would be structure together

    • An Array could be of single properties, the array rule was for property naming saying we would have to have a plural.

    • Array rule was an argument for the flattening that when you have an array, obviously the properties are at a hierarchy level below the array parent; so we insisted that they have a plural name because being an array does not necessarily make them an object.

  • VehicleDesc and Evaluation are aggregates are used by messages without using the parent level VehicleInfo.

    • It may be possible for messages to only be using OdometerReading and they included VehicleInfo to retrieve that, so we need to be careful to think that only these two aggregates are required without VehicleInfo.

  • Jeff reached out to category experts for body and trim in the meeting.

    • Body is only 1 and trim can have multiples. This lines up with the BMS definition and at this time we can promote the body aggregate up to the parent level of VehicleInfo.

  • ExteriorColor and InteriorColor will be children of Paint, and we will remove the hierarchy of Color as in the example.

    • Jeff will ask his catalog experts should be part of paint

  • VehicleInfo

    • Committee agrees that using VehicleInfo and all the properties every time you need a property from VehicleInfo is not a good idea.

    • Designers of messages or schemas should have the option to pick out the properties from VehicleInfo that they need. So if they only need OdometerInfo, they should be able to only use OdometerInfo.

      • This should be done by referencing the property that is needed from a commonType aggregate and not from copy and pasting.

    • Can we use required and optional fields?

      • The benefit here would be to have common messages.

      • VehicleLite was used for VINDecoder and was a smaller version of Vehicle. This was the vehicle Tshirt size approach concept.

      • The idea now is to only use the Max Vehicle and if you want to only use 18 of the 118 you can use those

      • We can have an implementation Guide to show

      • The CIECA reuse and Standardization

      • Schema will use all of the fields and some will be required and we can say in the implementation guide which are recommended.

        • Vehicle Model could be revamped.

        • One Schema = One Message

      • The thought was Next Gen implementation guide was going to be an open API document. This would mean we have an endpoint and a schema. For example, of VINDecode the open API would show the fields that were patinate to the VINDecode endpoint and the other fields would not be there. We did not discuss the fields that would not be needed.

      • Referencing is used for Small, Medium and Large

        • Referencing is one way of doing but not the only way

        • The committee likes the use of referencing.

  • Naming Convention

    • Do we need to reuse name in the field. For example when we have OdometerInfo do we need the fields to be called OdometerReading or should we drop Odometer from Reading.

    • This is a great concept, but what happens when we want to use OdoeterReading outside of the OdometerInfo and now it just says reading.

    • With referencing License Plate can be named whatever you want, not saying that its the best approach calling plate number, license plate number when referencing.

    • We cannot have a hard rule that says if the field name is in the object name that we do not want to repeat.

  • QA is next week.

  • There is a concern that the lite, medium, large options will cause more changes because we are not reusing the same object. So if we make a change to vehicle there will be more changes.

    • Mike will do the work with objects for Large Vehicle and a subset of vehicle lite for Vin Decoder so we can see the process and walk through it next meeting.

  • The Engine Options, Transmission Options. We need to revisit that and work through the naming guideline principals next meeting.

Thanks everyone for all the work, Great Meeting!

Open

Side Note: Video is way better than transcript. The Transcript has us all randomly saying okay, Yeah, and putting random words in places. JSON is Jason.

Action items

Decisions

1. The complete flattened object was rejected, and we agreed to stay with named objects.
2. Not to use the Chile Model because it is not supported by tools.
3. Guiding Principles is when we have properties that need to go together, they should be an Object and introduce a level of hierarchy
4. Guideline to always make sure that you are referencing the property definition. Look at the structure that it is in and determine the properties you want with best judgement.
5. Guiding Principle for Naming Convention that Desc should be used for property that describe something in a string.
6. Guiding Principle is no extraneous layers, layers that do not add value to the thing being transmitted instance schema. For an example the OrgInfo or Party Aggregates in the BMS.
7. Array Rule - Property naming should be plural
8. Promote VehicleDesc to the root of VehicleInfo, flattened and promoted.
9. Promote Body to the root of VehicleInfo

Participants

• Paulette Reed

• Paul Barry

• Dan Webster

• Mike Hastings

• Jeff Schroder

• Chrisa Hickey

• Brad Broerman

• Jeff Mueller

• Andy Bober

• Aaron Daniele

Participants in the meetings are noted for your information.  If you have questions on the committee’s activities, please contact a recent attendee. Architecture Committee