Ghcopilot Instr Power Platform Connector

---
name: ghcopilot-instr-power-platform-connector
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. Use when writing or reviewing power platform connector code and need idiomatic conventions and best practices.
license: CC-BY-NC-SA-4.0
metadata:
  version: "1.0.0"
  tags: [copilot-instruction, community, power-platform-connector]
  applyTo: "**/*.{json,md}"
  source: "awesome-copilot"
---

# 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
```json
{
  "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
```json
{
  "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
```json
{
  "name": "dynamicSchema",
  "in": "body",
  "schema": {
    "x-ms-dynamic-schema": {
      "operationId": "GetSchema",
      "parameters": {
        "table": {
          "parameter": "table"
        }
      },
      "value-path": "schema"
    }
  }
}
```

#### File Picker Capability
```json
{
  "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)
```json
{
  "x-ms-capabilities": {
    "testConnection": {
      "operationId": "TestConnection",
      "parameters": {
        "param1": "literal-value"
      }
    }
  }
}
```

#### Operation Context for Simulation
```json
{
  "x-ms-operation-context": {
    "simulate": {
      "operationId": "SimulateOperation",
      "parameters": {
        "param1": {
          "parameter": "inputParam"
        }
      }
    }
  }
}
```

### Basic OAuth Configuration
```json
{
  "type": "oauthSetting",
  "oAuthSettings": {
    "identityProvider": "oauth2",
    "clientId": "your-client-id",
    "scopes": ["scope1", "scope2"],
    "redirectMode": "Global"
  }
}
```

#### Multiple Security Definitions Example
```json
{
  "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
```json
{
  "x-ms-dynamic-values": {
    "operationId": "GetItems",
    "value-path": "id",
    "value-title": "name"
  }
}
```

### Policy Template for Routing
```json
{
  "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.