Align extraction filter config format with APIOps Toolkit

[petehauge]

Summary

The apiops-cli extraction filter configuration format does not match the APIOps Toolkit's format, preventing users from reusing their existing configuration.extractor.yaml files unchanged. The override (publish) configuration format is already aligned and requires no changes.

The goal is: a user with an existing APIOps Toolkit setup should be able to install apiops-cli and use their existing configuration.extractor.yaml and configuration.{env}.yaml files unchanged.

---

1. Extraction Filter Config — Filename

Aspect	apiops-cli (current)	APIOps Toolkit	Action Needed
Filename	configuration.extract.yaml	configuration.extractor.yaml	Accept both filenames; apiops init should generate configuration.extractor.yaml

---

2. Extraction Filter Config — Key Names (Main Issue)

The entire naming scheme differs. The CLI uses a *Names suffix convention while the Toolkit uses bare camelCase plurals matching the resource type's ConfigurationKey (derived from PluralName in src/common/*.cs).

CLI (current)	Toolkit (target)
apiNames	apis
productNames	products
backendNames	backends
namedValueNames	namedValues
loggerNames	loggers
diagnosticNames	diagnostics
tagNames	tags
policyFragmentNames	policyFragments
gatewayNames	gateways
versionSetNames	versionSets
groupNames	groups
subscriptionNames	subscriptions
workspaceNames	workspaces
schemaNames	(CLI-only, keep)
policyRestrictionNames	(CLI-only, keep)
documentationNames	(CLI-only, keep)

The filter config format also differs structurally for APIs — the Toolkit supports nested sub-resource filtering:

# Toolkit format (configuration.extractor.yaml)
apis:
  - apiName1
  - apiName2:
      operations: []
      diagnostics:
        - diagnosticName1
      schemas: []
      releases:
        - releaseName1

vs the CLI's flat string arrays:

# CLI format (configuration.extract.yaml)
apiNames:
  - apiName1
  - apiName2

Action needed

• Accept both *Names (current) and bare plural (Toolkit) key names
• Update apiops init templates to generate Toolkit-format keys by default
• Consider supporting nested sub-resource filtering for APIs (lower priority)

---

3. apimServiceName in Override Config

The Toolkit supports an apimServiceName root-level field in the override config (configuration.{env}.yaml) to specify the target APIM instance:

apimServiceName: myAPIMInstanceProd

namedValues:
  - name: my-named-value
    properties:
      value: "prod-value"

The CLI should accept this field gracefully (use it or ignore it without errors).

---

4. Override Config — Already Aligned ✅

The override (publish) configuration format is already compatible. Both tools use:

• The same section names (namedValues, backends, apis, loggers, diagnostics, etc.)
• The same name + properties nesting structure

No changes needed for override config format.

Verified against Azure/apiops configuration.prod.yaml and the Toolkit source code (src/common/Resource.cs, src/publisher/Configuration.cs).

---

Scope

~10-15 files across src, tests, and templates — primarily the config loader, filter config template, and associated tests.

---

Corrected from earlier version

⚠️ The original version of this issue contained fabricated Toolkit format claims (e.g., namedValuePairs, backendSettings, apiSettings as section names, and a flat property schema). These were incorrect — verified against the Toolkit source code and sample configs. The override format was already aligned; the real gap is the filter config key names.

---

Related

• Closes the gap left by fix: align override configuration format with APIOps Toolkit #102 which aligned the list-based override structure
• Comparison report generated from both tools run against the same APIM instance