Skip to content

power-platform-connector.instructions.md

Latest commit

 

History

History
430 lines (382 loc) · 18.9 KB

power-platform-connector.instructions.md

File metadata and controls

430 lines (382 loc) · 18.9 KB
title Power Platform Connectors Schema Development Instructions
description 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.
applyTo **/*.{json,md}

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)

  1. Always validate against Swagger 2.0 spec - The schema enforces strict Swagger 2.0 compliance

  2. 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.

  3. 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).

  4. 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.

  5. 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.

  6. Path-Level Extensions:

    • x-ms-notification-content: Use this to define notification content schemas for webhook path items.

  7. Operation-Level Capabilities:

    • x-ms-capabilities (at operation level): Use this to enable operation-specific capabilities such as chunkTransfer for large file transfers.

  8. 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).

  9. 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.

  10. 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

  1. 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.

  2. 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.

  3. 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

  1. 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.

  2. 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

  1. Use IntelliSense: These schemas provide rich autocomplete and validation capabilities that help during development.
  2. Follow Naming Conventions: Use descriptive names for operations and parameters to improve code readability.
  3. Implement Error Handling: Define appropriate response schemas and error codes to handle failure scenarios properly.
  4. Test Thoroughly: Validate schemas before deployment to catch issues early in the development process.
  5. Document Extensions: Comment Microsoft-specific extensions for team understanding and future maintenance.
  6. Version Management: Use semantic versioning in API info to track changes and compatibility.
  7. 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.