Why I've decided to write this

Once again I had a challenge that costed me some time and a lot of testing to reach the best solution. And now that I've managed to solve it, I'd like to share a little bit of my knowledge.
 

What happened?

In a namespace there were a lot of similar classes, so to make them simpler there were a superclass with comon properties. Also, there are relationships between them. I had to export one of them to JSON, but I couldn't change the superclasses, or I would break down the flow of many other integrations.

What made it all difficult was the problem that my JSON couldn't have the properties of the superclass. Ouch! I could export and take them off one by one, but.. what if someone changes the superclass?

And even worse... what happens with the relationships? If we export a relationship, we export another whole object, with all of its properties, but I couldn't have them either in the JSON.

A light in the end of the tunnel

Luckily, there is always a light in the end of the tunnel, and my light is the XData.

The solution is very simple: lets call the class that I had to export ClassToExport, the class with the relationship RelatedClass and the superclass SuperClass.

We'll have:

Class project.SuperClass Extends %Persistent {
    Property CommonProperty As %String;
}

Class project.ClassToExport Extends project.SuperClass {
    Property PropertyToExport As %String;
    Relationship RelationshipToExport As project.RelatedClass [ Cardinality = many, Inverse = RelatedProperty ];
}

Class project.RelatedClass Extends project.SuperClass {
    Property DontExportThis As %String;
    Property ExportThis As %String;
    Relationship RelatedProperty As project.ClassToExport [ Cardinality = one, Inverse = RelationshipToExport ];
}

In ClassToExport, I write the XData: there must be a name and a tag <Mapping> with the tags <Property>. The tag <Mapping> carries the xml namespace, xmlns="http://intersystems.com/jsonmapping", and the tags <Property> carry the properties described in %JSON.MappingProperty¹ (of the official documentation).

The magic trick is that everything that is not specified in the mapping will be ignored. So, if we change ClassToExport to:

Class project.ClassToExport Extends project.SuperClass {
    Property PropertyToExport As %String;
    Relationship RelationshipToExport As project.RelatedClass [ Cardinality = many, Inverse = RelatedProperty ];
    XData MappingJSON {
        <Mapping xmlns = "http://intersystems.com/jsonmapping">
            <Property Name = "PropertyToExport" FieldName = "Property-JSON"/>
            <Property Name = "RelationshipToExport" FieldName = "RelatedClassJSON"/>
        </Mapping>
    }
}

we'll have in the JSON something like:

{
   "Property-JSON":"value",
   "RelatedClassJSON": [
      {"CommonProperty":"value", "DontExportThis":"value", "ExportThis":"value"},
      {"CommonProperty":"value", "DontExportThis":"value", "ExportThis":"value"}
   ]
}

So the names of the ClassToExport are ready, and only the properties we want are in the JSON, but the RelatedClass still has work to do.

Then, we change RelatedClass with an XData with the same name to arrange their properties:

Class project.RelatedClass Extends project.SuperClass {
    Property DontExportThis As %String;
    Property ExportThis As %String;
    Relationship RelatedProperty As project.ClassToExport [ Cardinality = one, Inverse = RelationshipToExport ];
    XData MappingJSON
    {
        <Mapping xmlns = "http://intersystems.com/jsonmapping">
            <Property Name = "DontExportThis" Include="None"/>
            <Property Name = "ExportThis" Include="INOUT"/>
            <Property Name = "CommonProperty" Include="INOUT"/>
        </Mapping>
    }
    
    
}

so we'll have in the JSON somehting like:

{
   "Property-JSON":"value",
   "RelatedClassJSON": [
      {"CommonProperty":"value", "ExportThis":"value"},
      {"CommonProperty":"value", "ExportThis":"value"}
   ]
}

which is what we want.

It is interesting to observe that for the property "DontExportThis", I specified a tag with INclude="None". This is the same of not putting any ta at all for that property.

¹ read also %JSON.PropertyParameters to understant what each property does.
 

Thank you for reading and I hope the article was useful!

Feel free to ask me for doubts or to get in touch if you think I can help in some specific case. I'll be happy to help!