cancel
Showing results for 
Search instead for 
Did you mean: 
Reply
Highlighted
cafee888
Level: Powered On

x-ms-dynamic-schema in Custom API

Hi

 

I would be building some Custom APIs for Powerapps.

And most times the return data columns will be dynamic

 

Understand that there is a tag "x-ms-dynamic-schema" for swagger

 

Any examples for using it in a response? (swagger) and Json schema format

 

Thanks in advance

3 REPLIES 3
joshbooker
Level 8

Re: x-ms-dynamic-schema in Custom API

That's a good quuestion.  You'd think after 7 months there would be an answer from a PowerApps team member.

nihaue
Level: Power Up

Re: x-ms-dynamic-schema in Custom API

I actually just built a sample that uses this, you can find it here. It was written in C#, and requires at least the 2.0.1 version of T-Rex library for metadata generation.

 

In terms of the raw swagger, here is what the paths would look like (/api/contacts/{name} is the actual operation, /api/contacts/schema is used to lookup the schema). Things to note would be:

  • The main operation has a parameter named contactType. It is based on this parameter that a schema will be chosen for the output. There is one schema for Email addresses, and a different schema for phone numbers.
  • The type returned from the main operation which points to #/definitions/ContactInfo elsewhere in the swagger
  • The operation id of the schema lookup operation is GetContactInfoSchema (this will be important later), and it requires a parameter named type (also important later)

 

"paths": {
        "/api/contacts/{name}": {
            "get": {
                "tags": [
                    "DynamicSchemas"
                ],
                "summary""Get Contact Info",
                "description""Gets contact info of the specified type",
                "operationId""GetContactInfo",
                "consumes": [],
                "produces": [
                    "application/json",
                    "text/json",
                    "application/xml",
                    "text/xml"
                ],
                "parameters": [
                    {
                        "name""name",
                        "in""path",
                        "required"true,
                        "type""string",
                        "x-ms-summary""Contact Name"
                    },
                    {
                        "name""contactType",
                        "in""query",
                        "description""Try either \"Phone\" or \"Email\"",
                        "required"true,
                        "type""string",
                        "x-ms-summary""Contact Type"
                    }
                ],
                "responses": {
                    "200": {
                        "description""OK",
                        "schema": {
                            "$ref": "#/definitions/ContactInfo"
                        }
                    },
                    "400": {
                        "description""Invalid type specified"
                    },
                    "default": {
                        "description""OK",
                        "schema": {
                            "$ref""#/definitions/ContactInfo"
                        }
                    }
                },
                "x-ms-visibility""important"
            }
        },
        "/api/contacts/schema": {
            "get": {
                "tags": [
                    "DynamicSchemas"
                ],
                "summary""GetContactInfoSchema",
                "operationId""GetContactInfoSchema",
                "consumes": [],
                "produces": [
                    "application/json",
                    "text/json",
                    "application/xml",
                    "text/xml"
                ],
                "parameters": [
                    {
                        "name""type",
                        "in""query",
                        "required"true,
                        "type""string"
                    }
                ],
                "responses": {
                    "200": {
                        "description""OK",
                        "schema": {
                            "type""object"
                        }
                    },
                    "400": {
                        "description""Invalid type specified"
                    },
                    "default": {
                        "description""OK",
                        "schema": {
                            "type""object"
                        }
                    }
                },
                "x-ms-visibility""internal"
            }
        },
 

Now none of this would mean anything without the x-ms-dynamic-schema vendor extension being present on the type definitino that was referenced by our main operation. Which type definition? #/definitions/ContactInfo of course. So what is in the definitions section of the swagger for that?

  • Within the x-ms-dynamic-schema section, it points to the operation id of the schema lookup operation.
  • In the parameters section is a mapping of the parameters of that operation. As we saw above it took in a parameter named type, so there that parameter is called out. If we were going to hard code the value, we could just say "type": "somevalue". But since we are mapping that to a parameter used for our main operation, we have an object assigned instead with a property named parameter (to indicate that this is a parameter mapping), and a value of contactType (which matches the parameter name of the main operation). 
  • For the value-path we see schema. That's because of the shape of the output from the GetContactInfoSchema operation (we'll get to that next)

 

    "definitions": {
        "ContactInfo": {
            "type""object",
            "properties": {},
            "x-ms-dynamic-schema": {
                "operationId""GetContactInfoSchema",
                "parameters": {
                    "type": {
                        "parameter""contactType"
                    }
                },
                "value-path""Schema"
            }
        }, 
 
nihaue
Level: Power Up

Re: x-ms-dynamic-schema in Custom API

 

So what is the shape of the output when we call the operation to get the schema? It will look something like this (below). Notice the Schema property -- that's what the value-path was pointing to.

 

{
  "Schema": {
    "title""Email",
    "type""object",
    "properties": {
      "localPart": {
        "type""string"
      },
      "hostPart": {
        "type""string"
      },
      "displayName": {
        "type""string"
      }
    }
  }
}
 
Hopefully that gave a little bit of a picture of how this can work. It took quite a bit of trial/error/reverse engineering to figure it out, so I wanted to make sure it gets written down somewhere.

Helpful resources

Announcements
thirdimage

Power Automate Community User Group Member Badge

Fill out a quick form to claim your user group badge now!

sixthImage

Power Platform World Tour

Find out where you can attend!

Power Platform 2019 release wave 2 plan

Power Platform 2019 release wave 2 plan

Features releasing from October 2019 through March 2020

fifthimage

Microsoft Learn

Learn how to build the business apps that you need.

Top Kudoed Authors (Last 30 Days)
Users online (4,477)