cancel
Showing results for 
Search instead for 
Did you mean: 
Reply
Highlighted
Frequent Visitor

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
Highlighted
Kudo Kingpin
Kudo Kingpin

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.

Highlighted
Anonymous
Not applicable

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"
            }
        }, 
 
Highlighted
Anonymous
Not applicable

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
August 2020 Community Challenge: Can You Solve These?

August 2020 Community Challenge: Can You Solve These?

We're excited to announce our first cross-community 'Can You Solve These?' challenge!

secondImage

Return to Workplace

Reopen responsibly, monitor intelligently, and protect continuously with solutions for a safer work environment.

secondImage

Super Users Coming in August

We are excited for the next Super User season.

secondImage

Community User Group Member Badges

FIll out a quick form to claim your community user group member badge today!

secondImage

Power Platform 2020 release wave 2 plan

Features releasing from October 2020 through March 2021

Top Solution Authors
Top Kudoed Authors
Users online (7,674)