Awesome-omni-skill power-platform-connector

Comprehensive development guidelines for Power Platform Custom Connectors using JSON Schema definitions. Covers API definitions (Swagger 2.0), API properties, and settings configuration with Microsoft extensions. Triggers on: **/*.{json,md}

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/development/power-platform-connector" ~/.claude/skills/diegosouzapw-awesome-omni-skill-power-platform-connector && rm -rf "$T"

manifest: skills/development/power-platform-connector/SKILL.md

source content

Power Platform Connectors Schema Development Instructions

Project Overview

This workspace contains JSON Schema definitions for Power Platform Custom Connectors, specifically for the

paconn

(Power Apps Connector) tool. The schemas validate and provide IntelliSense for:

API Definitions (Swagger 2.0 format)
API Properties (connector metadata and configuration)
Settings (environment and deployment configuration)

File Structure Understanding

1. apiDefinition.swagger.json

Purpose: This file contains Swagger 2.0 API definitions with Power Platform extensions.
Key Features:
- Standard Swagger 2.0 properties including info, paths, definitions, and more.
- Microsoft-specific extensions that begin with
```
x-ms-*
```
  prefixes.
- Custom format types specifically designed for Power Platform such as
```
date-no-tz
```
  and
```
html
```
  .
- Dynamic schema support that provides runtime flexibility.
- Security definitions that support OAuth2, API Key, and Basic Auth authentication methods.

2. apiProperties.json

Purpose: This file defines connector metadata, authentication configurations, and policy configurations.
Key Components:
- Connection Parameters: These support various authentication types including OAuth, API Key, and Gateway configurations.
- Policy Template Instances: These handle data transformation and routing policies for the connector.
- Connector Metadata: This includes publisher information, capabilities, and branding elements.

3. settings.json

Purpose: This file provides environment and deployment configuration settings for the paconn tool.
Configuration Options:
- Environment GUID targeting for specific Power Platform environments.
- File path mappings for connector assets and configuration files.
- API endpoint URLs for both production and testing environments (PROD/TIP1).
- API version specifications to ensure compatibility with Power Platform services.

Development Guidelines

When Working with API Definitions (Swagger)

Always validate against Swagger 2.0 spec - The schema enforces strict Swagger 2.0 compliance
Microsoft Extensions for Operations:
- ```
x-ms-summary
```
  : Use this to provide user-friendly display names and ensure you use title case formatting.
- ```
x-ms-visibility
```
  : Use this to control parameter visibility with values of
```
important
```
  ,
```
advanced
```
  , or
```
internal
```
  .
- ```
x-ms-trigger
```
  : Use this to mark operations as triggers with values of
```
batch
```
  or
```
single
```
  .
- ```
x-ms-trigger-hint
```
  : Use this to provide helpful hint text that guides users when working with triggers.
- ```
x-ms-trigger-metadata
```
  : Use this to define trigger configuration settings including kind and mode properties.
- ```
x-ms-notification
```
  : Use this to configure webhook operations for real-time notifications.
- ```
x-ms-pageable
```
  : Use this to enable pagination functionality by specifying the
```
nextLinkName
```
  property.
- ```
x-ms-safe-operation
```
  : Use this to mark POST operations as safe when they don't have side effects.
- ```
x-ms-no-generic-test
```
  : Use this to disable automatic testing for specific operations.
- ```
x-ms-operation-context
```
  : Use this to configure operation simulation settings for testing purposes.
Microsoft Extensions for Parameters:
- ```
x-ms-dynamic-list
```
  : Use this to enable dynamic dropdown lists populated from API calls.
- ```
x-ms-dynamic-values
```
  : Use this to configure dynamic value sources that populate parameter options.
- ```
x-ms-dynamic-tree
```
  : Use this to create hierarchical selectors for nested data structures.
- ```
x-ms-dynamic-schema
```
  : Use this to allow runtime schema changes based on user selections.
- ```
x-ms-dynamic-properties
```
  : Use this for dynamic property configuration that adapts to context.
- ```
x-ms-enum-values
```
  : Use this to provide enhanced enum definitions with display names for better user experience.
- ```
x-ms-test-value
```
  : Use this to provide sample values for testing, but never include secrets or sensitive data.
- ```
x-ms-trigger-value
```
  : Use this to specify values specifically for trigger parameters with
```
value-collection
```
  and
```
value-path
```
  properties.
- ```
x-ms-url-encoding
```
  : Use this to specify URL encoding style as either
```
single
```
  or
```
double
```
  (defaults to
```
single
```
  ).
- ```
x-ms-parameter-location
```
  : Use this to provide parameter location hints for the API (AutoRest extension - ignored by Power Platform).
- ```
x-ms-localizeDefaultValue
```
  : Use this to enable localization for default parameter values.
- ```
x-ms-skip-url-encoding
```
  : Use this to skip URL encoding for path parameters (AutoRest extension - ignored by Power Platform).
Microsoft Extensions for Schemas:
- ```
x-ms-notification-url
```
  : Use this to mark a schema property as a notification URL for webhook configurations.
- ```
x-ms-media-kind
```
  : Use this to specify the media type for content, with supported values of
```
image
```
  or
```
audio
```
  .
- ```
x-ms-enum
```
  : Use this to provide enhanced enum metadata (AutoRest extension - ignored by Power Platform).
- Note that all parameter extensions listed above also apply to schema properties and can be used within schema definitions.
Root-Level Extensions:
- ```
x-ms-capabilities
```
  : Use this to define connector capabilities such as file-picker and testConnection functionality.
- ```
x-ms-connector-metadata
```
  : Use this to provide additional connector metadata beyond the standard properties.
- ```
x-ms-docs
```
  : Use this to configure documentation settings and references for the connector.
- ```
x-ms-deployment-version
```
  : Use this to track version information for deployment management.
- ```
x-ms-api-annotation
```
  : Use this to add API-level annotations for enhanced functionality.
Path-Level Extensions:
- ```
x-ms-notification-content
```
  : Use this to define notification content schemas for webhook path items.
Operation-Level Capabilities:
- ```
x-ms-capabilities
```
  (at operation level): Use this to enable operation-specific capabilities such as
```
chunkTransfer
```
  for large file transfers.
Security Considerations:
- You should define appropriate
```
securityDefinitions
```
  for your API to ensure proper authentication.
- Multiple security definitions are allowed - you can define up to two auth methods (e.g., oauth2 + apiKey, basic + apiKey).
- Exception: If using "None" authentication, no other security definitions can be present in the same connector.
- You should use
```
oauth2
```
  for modern APIs,
```
apiKey
```
  for simple token authentication, and consider
```
basic
```
  auth only for internal/legacy systems.
- Each security definition must be exactly one type (this constraint is enforced by oneOf validation).
Parameter Best Practices:
- You should use descriptive
```
description
```
  fields to help users understand each parameter's purpose.
- You should implement
```
x-ms-summary
```
  for better user experience (title case is required).
- You must mark required parameters correctly to ensure proper validation.
- You should use appropriate
```
format
```
  values (including Power Platform extensions) to enable proper data handling.
- You should leverage dynamic extensions for better user experience and data validation.
Power Platform Format Extensions:

```
date-no-tz
```
: This represents a date-time that has no time-offset information.
```
html
```
: This format tells clients to emit an HTML editor when editing and an HTML viewer when viewing content.

Standard formats include:

int32

int64

float

double

byte

binary

date

date-time

password

email

uri

uuid

When Working with API Properties

Connection Parameters:
- You should choose appropriate parameter types such as
```
string
```
  ,
```
securestring
```
  , or
```
oauthSetting
```
  .
- You should configure OAuth settings with correct identity providers.
- You should use
```
allowedValues
```
  for dropdown options when appropriate.
- You should implement parameter dependencies when needed for conditional parameters.
Policy Templates:
- You should use
```
routerequesttoendpoint
```
  for backend routing to different API endpoints.
- You should implement
```
setqueryparameter
```
  for setting default values on query parameters.
- You should use
```
updatenextlink
```
  for pagination scenarios to handle paging correctly.
- You should apply
```
pollingtrigger
```
  for trigger operations that require polling behavior.
Branding and Metadata:
- You must always specify
```
iconBrandColor
```
  as this property is required for all connectors.
- You should define appropriate
```
capabilities
```
  to specify whether your connector supports actions or triggers.
- You should set meaningful
```
publisher
```
  and
```
stackOwner
```
  values to identify the connector's ownership.

When Working with Settings

Environment Configuration:
- You should use proper GUID format for
```
environment
```
  that matches the validation pattern.
- You should set correct
```
powerAppsUrl
```
  and
```
flowUrl
```
  for your target environment.
- You should match API versions to your specific requirements.
File References:
- You should maintain consistent file naming with the defaults of
```
apiProperties.json
```
  and
```
apiDefinition.swagger.json
```
  .
- You should use relative paths for local development environments.
- You should ensure icon file exists and is properly referenced in your configuration.

Schema Validation Rules

Required Properties

API Definition:
```
swagger: "2.0"
```
,
```
info
```
(with
```
title
```
and
```
version
```
),
```
paths
```
API Properties:
```
properties
```
with
```
iconBrandColor
```
Settings: No required properties (all optional with defaults)

Pattern Validation

Vendor Extensions: Must match
```
^x-(?!ms-)
```
pattern for non-Microsoft extensions
Path Items: Must start with
```
/
```
for API paths

Environment GUID: Must match UUID format pattern

^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

URLs: Must be valid URIs for endpoint configurations
Host Pattern: Must match
```
^[^{}/ :\\\\]+(?::\\d+)?$
```
(no spaces, protocols, or paths)

Type Constraints

Security Definitions:
- Up to two security definitions allowed in
```
securityDefinitions
```
  object
- Each individual security definition must be exactly one type (oneOf validation:
```
basic
```
  ,
```
apiKey
```
  ,
```
oauth2
```
  )
- Exception: "None" authentication cannot coexist with other security definitions
Parameter Types: Limited to specific enum values (
```
string
```
,
```
number
```
,
```
integer
```
,
```
boolean
```
,
```
array
```
,
```
file
```
)
Policy Templates: Type-specific parameter requirements
Format Values: Extended set including Power Platform formats
Visibility Values: Must be one of
```
important
```
,
```
advanced
```
, or
```
internal
```
Trigger Types: Must be
```
batch
```
or
```
single
```

Additional Validation Rules

$ref References: Should only point to
```
#/definitions/
```
,
```
#/parameters/
```
, or
```
#/responses/
```
Path Parameters: Must be marked as
```
required: true
```
Info Object: Description should be different from title
Contact Object: Email must be valid email format, URL must be valid URI
License Object: Name is required, URL must be valid URI if provided
External Docs: URL is required and must be valid URI
Tags: Must have unique names within the array
Schemes: Must be valid HTTP schemes (
```
http
```
,
```
https
```
,
```
ws
```
,
```
wss
```
)
MIME Types: Must follow valid MIME type format in
```
consumes
```
and
```
produces
```

Common Patterns and Examples

API Definition Examples

Basic Operation with Microsoft Extensions

{
  "get": {
    "operationId": "GetItems",
    "summary": "Get items",
    "x-ms-summary": "Get Items",
    "x-ms-visibility": "important",
    "description": "Retrieves a list of items from the API",
    "parameters": [
      {
        "name": "category",
        "in": "query",
        "type": "string",
        "x-ms-summary": "Category",
        "x-ms-visibility": "important",
        "x-ms-dynamic-values": {
          "operationId": "GetCategories",
          "value-path": "id",
          "value-title": "name"
        }
      }
    ],
    "responses": {
      "200": {
        "description": "Success",
        "x-ms-summary": "Success",
        "schema": {
          "type": "object",
          "properties": {
            "items": {
              "type": "array",
              "x-ms-summary": "Items",
              "items": {
                "$ref": "#/definitions/Item"
              }
            }
          }
        }
      }
    }
  }
}

Trigger Operation Configuration

{
  "get": {
    "operationId": "WhenItemCreated",
    "x-ms-summary": "When an Item is Created",
    "x-ms-trigger": "batch",
    "x-ms-trigger-hint": "To see it work now, create an item",
    "x-ms-trigger-metadata": {
      "kind": "query",
      "mode": "polling"
    },
    "x-ms-pageable": {
      "nextLinkName": "@odata.nextLink"
    }
  }
}

Dynamic Schema Example

{
  "name": "dynamicSchema",
  "in": "body",
  "schema": {
    "x-ms-dynamic-schema": {
      "operationId": "GetSchema",
      "parameters": {
        "table": {
          "parameter": "table"
        }
      },
      "value-path": "schema"
    }
  }
}

File Picker Capability

{
  "x-ms-capabilities": {
    "file-picker": {
      "open": {
        "operationId": "OneDriveFilePickerOpen",
        "parameters": {
          "dataset": {
            "value-property": "dataset"
          }
        }
      },
      "browse": {
        "operationId": "OneDriveFilePickerBrowse",
        "parameters": {
          "dataset": {
            "value-property": "dataset"
          }
        }
      },
      "value-title": "DisplayName",
      "value-collection": "value",
      "value-folder-property": "IsFolder",
      "value-media-property": "MediaType"
    }
  }
}

Test Connection Capability (Note: Not Supported for Custom Connectors)

{
  "x-ms-capabilities": {
    "testConnection": {
      "operationId": "TestConnection",
      "parameters": {
        "param1": "literal-value"
      }
    }
  }
}

Operation Context for Simulation

{
  "x-ms-operation-context": {
    "simulate": {
      "operationId": "SimulateOperation",
      "parameters": {
        "param1": {
          "parameter": "inputParam"
        }
      }
    }
  }
}

Basic OAuth Configuration

{
  "type": "oauthSetting",
  "oAuthSettings": {
    "identityProvider": "oauth2",
    "clientId": "your-client-id",
    "scopes": ["scope1", "scope2"],
    "redirectMode": "Global"
  }
}

Multiple Security Definitions Example

{
  "securityDefinitions": {
    "oauth2": {
      "type": "oauth2",
      "flow": "accessCode",
      "authorizationUrl": "https://api.example.com/oauth/authorize",
      "tokenUrl": "https://api.example.com/oauth/token",
      "scopes": {
        "read": "Read access",
        "write": "Write access"
      }
    },
    "apiKey": {
      "type": "apiKey",
      "name": "X-API-Key",
      "in": "header"
    }
  }
}

Note: Maximum of two security definitions can coexist, but "None" authentication cannot be combined with other methods.

Dynamic Parameter Setup

{
  "x-ms-dynamic-values": {
    "operationId": "GetItems",
    "value-path": "id",
    "value-title": "name"
  }
}

Policy Template for Routing

{
  "templateId": "routerequesttoendpoint",
  "title": "Route to backend",
  "parameters": {
    "x-ms-apimTemplate-operationName": ["GetData"],
    "x-ms-apimTemplateParameter.newPath": "/api/v2/data"
  }
}

Best Practices

Use IntelliSense: These schemas provide rich autocomplete and validation capabilities that help during development.
Follow Naming Conventions: Use descriptive names for operations and parameters to improve code readability.
Implement Error Handling: Define appropriate response schemas and error codes to handle failure scenarios properly.
Test Thoroughly: Validate schemas before deployment to catch issues early in the development process.
Document Extensions: Comment Microsoft-specific extensions for team understanding and future maintenance.
Version Management: Use semantic versioning in API info to track changes and compatibility.
Security First: Always implement appropriate authentication mechanisms to protect your API endpoints.

Troubleshooting

Common Schema Violations

Missing required properties:

swagger: "2.0"

info.title

info.version

paths

Invalid pattern formats:
- GUIDs must match exact format
```
^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
```
- URLs must be valid URIs with proper scheme
- Paths must start with
```
/
```
- Host must not include protocol, paths, or spaces
Incorrect vendor extension naming: Use
```
x-ms-*
```
for Microsoft extensions,
```
^x-(?!ms-)
```
for others
Mismatched security definition types: Each security definition must be exactly one type
Invalid enum values: Check allowed values for
```
x-ms-visibility
```
,
```
x-ms-trigger
```
, parameter types
$ref pointing to invalid locations: Must point to
```
#/definitions/
```
,
```
#/parameters/
```
, or
```
#/responses/
```
Path parameters not marked as required: All path parameters must have
```
required: true
```
Type 'file' in wrong context: Only allowed in
```
formData
```
parameters, not in schemas

API Definition Specific Issues

Dynamic schema conflicts: Can't use
```
x-ms-dynamic-schema
```
with fixed schema properties
Trigger configuration errors:
```
x-ms-trigger-metadata
```
requires both
```
kind
```
and
```
mode
```
Pagination setup:
```
x-ms-pageable
```
requires
```
nextLinkName
```
property
File picker misconfiguration: Must include both
```
open
```
operation and required properties
Capability conflicts: Some capabilities may conflict with certain parameter types
Test value security: Never include secrets or PII in
```
x-ms-test-value
```
Operation context setup:
```
x-ms-operation-context
```
requires a
```
simulate
```
object with
```
operationId
```
Notification content schema: Path-level
```
x-ms-notification-content
```
must define proper schema structure
Media kind restrictions:
```
x-ms-media-kind
```
only supports
```
image
```
or
```
audio
```
values
Trigger value configuration:
```
x-ms-trigger-value
```
must have at least one property (
```
value-collection
```
or
```
value-path
```
)

Validation Tools

Use JSON Schema validators to check your schema definitions for compliance.
Leverage VS Code's built-in schema validation to catch errors during development.

Test with paconn CLI before deployment using:

paconn validate --api-def apiDefinition.swagger.json

Validate against Power Platform connector requirements to ensure compatibility.
Use the Power Platform Connector portal for validation and testing in the target environment.
Check that operation responses match expected schemas to prevent runtime errors.

Remember: These schemas ensure your Power Platform connectors are properly formatted and will work correctly in the Power Platform ecosystem.