[Feature] Print a consolidated schema (including inheritance) for a schema Type

[ghost]

Hi Peter/IonSchema team,

We’re using inheritance to create our final schemas. Our clients care about specific schema types only and it’s more meaningful for them to see the consolidated schema for a specific type in our design docs including the extended fields.

Since the whole ION schema is loaded by the ‘IonSchemaSystem’, a support to be able to generate a pretty string would go a long way in writing design docs.

Example: Our actual schema that uses inheritance to make things easier to build

type::{
    name: InternalParent,
    type: struct,
    fields: {
        commonField1: {
            type: string 
        }
    },
}

type::{
    name: FinalSchema1,
    type: InternalParent,
    fields: {
        finalField1: {
            type: string  
        }
    },
}

Consolidated view we want for our clients to see in design java doc who only care about FinalSchema1:

type::{
    name: FinalSchema1,
    type: struct,
    fields: {
       commonField1: {
            type: string 
        },
        finalField1: {
            type: string  
        }
    },
}

[pbcornell]

Agreed, this sounds like a useful capability. Note that some constraints would be more straightforward to consolidate than others. Your example of consolidating a fields constraint seems reasonable, and would presumably recurse into field-level constraints (e.g., FinalSchema1 might add a codepoint_length constraint to InternalParent's commonField1). Other constraints (well, specifically the regex constraint) would likely prove challenging to merge, so perhaps the consolidated view would simply represent each regex individually.

I suspect this belongs as part of an Ion Schema Doc (isd? isdoc? isldoc?) tool; however, there are also potential performance benefits to consolidation. Consider the following:

type::{
  name: A,
  codepoint_length: range::[0, 200],
}
type::{
  name: B,
  type: A,
  codepoint_length: range::[100, 300],
}

When validating against type B, less processing would be required to check a consolidated codepoint_length: range::[100, 200] constraint versus checking the two overlapping ranges individually (and assuming it's agreeable to spread the up-front consolidation cost across multiple validations).

[pbcornell]

@GokulPraveenB, I'd like to make sure I understand what would best meet your needs in order to avoid under- or over-engineering. Are you looking for an API that would return the consolidated/flattened Ion for a type? or a tool that would generate HTML documentation for a schema that would include the consolidated Ion?

You mention an interest in using the consolidated Ion in design docs; would an API meet that need? If you have near-, mid-, long-term ideas here, feel free to share--thank you!

[ghost]

Hi @pbcornell , sorry for the delay. Because of a push from larger initiative, we modeled our data in Smithy since API request/response can also be modeled even though data modeling capabilities of Smithy are lacking compared to ION Schema. Sorry for this digression.

In the order of usefulness from my original use-case's perspective

1. An API in the IonSchemaSystem that could flatten a type which we could expose to our clients.
2. An additional tool to which would automatically embed the flattened type in HTML documentation would've been even better.

Hopefully this feedback helps! Thanks for listening and we hope to use ION Schema in the future for other use-cases.

[pbcornell]

Thank you for circling back @GokulPraveenB, and for the additional clarification. I suspect your feature request would be useful for others as well; in the meantime, glad to know you found a path forward that meets your needs.