2023-07-25 Architecture Meeting Minutes

🔓 Public Page

Agenda

• Network/Welcome

• Antitrust Statement

  • This meeting is subject to the terms of our anti-trust statement shown here.  In addition, this meeting may be recorded. 

• Review Meeting Minutes

• Vacation

• Review Mikes Changes

• Andy Demo versioning

• Review JIRA

Meeting Minutes

• Antitrust Accepted

• Meeting Minutes Reviewed Accepted

• Paulette will be returning from a mini vacation next week on Tuesday, Meeting is being cancelled.

• Dan will be able to attend CONNEX.

• Mike’s work review

  • Last week we went though the objects that were changed adn this week we were going to do a code review on the schema.

  • Difference between objects and schema?

    • The Instance that shows how the objects are used shows the code instead of looking at the objects themselves.

  • New Stoplight project was created.

    • You may have received an invite for a new project in stoplight, this was due to Mike creating a new project so we could save the original version.

  • The use case here is it's showing up a buyer, who's the user who's a consumer that iss buying some parts? Basically the user the bill to who's paying the bill, the ship to where it's being shipped to, and then the supplier or the seller of the parts and then a parts list.

    • This example shows the new objects that I've added to the schema.

      • The first one is the user

        • ID which is basically a GUID's and it has username.

        • Localization code that basically tell the app what language to present in

        • Primary contact: You know which has the name and the person's name and their address, and then I have a list of phone numbers.

        • New Phone Number types here is TX; tells you that this phone number is text able, and you can send them a text message.

        • New emails Array; just have one email in the array example.

        • Primary contact uses a contact object.

          • 3 objects and the user is actually within the user here. That's one of the objects that contact is a second object, and then the third object is a company object and I have used that down and ship and the supplier.

          • The supplier you can see he's got a company object which has a an ID and then it has a company name and then I have a primary contact here so.

      • In the Original version we had party and contact, and this adds user and company.

      • Address was added to Contact.

      • Do we need to have Party anymore?

        • The Claims concept that could be a user could be a company.

        • This does not replace party; just adds a new container for contacts.

        • Company and Party are very similar.

          • Party is more tailored to insurance claims.

          • Company is more tailored to ecommerce.

        • We can have a user inside a company object and a party within a party.

  • Talk about the additional properties and the patterns and antipatterns.

    • We are going to allow additional properties, which I think we want to, it makes it harder to uh, more work to make invalid instances.

  • Since the BMS days when we have invalid stuff, and it passed the test. If it's invalid, even though it might have been designed 10 versions ago to show some other validation error. We do not want to get back to that.

  • Localization code.

    • At one point we had country and language in there, but it's the same concept, right?

    • This is one of the languages we support and probably some manageable number of those instead of the hundreds that some United Nation organization supports.

    • New code list for the localization codes and new enum and I just put in four so far, you know, kind of the zero-based budgeting, but we could add more for Europe or whatever countries we are going to support.

  • username is one word by google so we are okay with-it being username instead of userName.

  • Weakness in our BA Data Dictionary design.

    • We have references but then we have others such as ID, Type that we repeat instead of referencing.

      • We can fix this weakness by naming one userId and the phoneType and emailType.

      • Mike showed where his does reference ID in the BA Data Dictionary.

      • Model type is email type and then the phone numbers array type is a phone type.

      • This approach allows us to meet our rule/standard to keep these code lists small and separate as much as possible.

  • Of all the schema changes I made, the email array caused the most editing within the instance docs.

  • The supplier includes some of the company properties such as company name and there's also a company URL company alias. This is an example of the properties that are not in a party.

  • The examples are following that practice where any property within an object can be defined as a property in the BA dictionary.

    • Attention in Notes: Not sure we've stated that as a rule somewhere, but it you're applying it as a rule that every that we don't do inline definitions within an object model, they're all references.

      And then the I think the further rule that I'm a little less comfortable as that it also the thing that it references has to be letter for letter, the same as what you're calling it in the object definition.

    • In the example we looked at, we just saw the model where you have an email object that has the type of email and then the email address and something else preferred indicator and same thing for phone number. Then we see, here in contact we don't have a contact to his type as primary bill to and ship to. And I just observed the company ID's three different company ID and they were just named in the property name.

      • Restatement: would have been possible to follow the model we did for phone number and email to have an array of contacts, one of whose property was a contact type and to fulfill the purpose of 641 through 652, you could have a contact type property whose enumerations would be primary bill to and ship to and in like manner we had a CRM company ID, a company ID and a third one where again we yeah, we could have made them companies with a company type.

      • The example is using flattening.

      • Essential thing: that when you make it a name value pair ID type and ID number, the next thing you know we've found people having a ID type which Headquarters or something? The ID number is true or false and that's just so much nonsense. And yeah, the thing is, JSON is already organized as name value pairs and the name is the property name and the value is what's after the colon and to make name value pairs within name value pairs is silliness that we're not going To do and we have done that in version one. We had properties called subsidiary company ID I, underwriting company ID etcetera. Same idea.

  • Show mew endpoint schema that called the parts invoice and that's what I use to create the Instance doc.

    • Example shows the three modified objects or three new objects.

    • user.

    • Repair facility with the company built to with contact ship to with contact supplier with a company and then I you know I'm using the parts object out of CAPIS.

    • Have not created a new Stoplight example of this API, just you know it still has the claim service, but I wanted to show you this schema and then the other thing I can show you really quick is the test instances I have a new folder called parts invoice and I think I showed you the valid. I also have five invalid messages to test certain things.

      • Invalid Test Instances include an invalid company, invalid contact, invalid email.

  • All Changes look good.

• Implementation difficulty

  • Some API developers pushed back on the CAPIS first version; and the idea of being able to allow them to change from the standard we are creating is hard concept.

  • Additional Properties false is a anti pattern which is going to cause issues.

    • For example, if you ever have a get endpoint and you add new properties that the breaking change for the folks, you're sending things back to and umm, where I'm coming to the conclusion that. Adding properties to objects from time to time is going to be pretty common, and the Bickley wouldn't be treated as a breaking change for implementations, but it's certainly breaking change for folks who use these schemas. Let's say additional properties false and then do a Jason schema validation on them and I I'm very interested to hear if that's the way you guys think of it at your companies too or not.

    • I remember initially being very eager to put in additional properties to false because it made the AH process of making useful. Instances better and showed me that I had made instances that where at the wrong level of the hierarchy or whatever and it didn't detect it because it just considered all my mistakes to be additional properties. But I want if the topic of not setting additional properties to false hasn't been part of our discussions before, I want to introduce it today and before we go out with us as a release, come to a conclusion one or the other.

    • We wanted people to be able to easily extend these things and then we changed it to false after you guys made that realization that it just considers everything and now it's on to, we're going back the other way.

    • We could add in at like a separate guideline on how best your suggestions on how best to use things. And I know in some in certain places I've seen where developers will code something like saying take the third item and the third item is typically the address, but they don't look it up by name.

    • Add to Agenda Item for next meeting.

Great Work everyone

Up Next

• Network/Welcome

• Antitrust

• Review Meeting Minutes

• Discuss Additional Properties being set to False or True

• Review Work Changes

Action items

Decisions

Reference