Power-Platform-Connector

# 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 neve