power-platform-connectors has no hand-authored variant — the whole overlay assumes Postman generation

[PBNZ]

What / why

The power-platform-connectors type assumes connector definitions are generated from an
upstream Postman collection. There is no variant for repos that hand-author the definitions,
and hand-authoring is a legitimate — sometimes forced — choice.

Everything in the overlay is built around that one pipeline:

File	Assumes
core/Dockerfile	pinned Node toolchain for the generator
core/scripts/generate.mjs	Postman → Swagger conversion
core/connectors.config.json	sourceUrl pointing at a Postman collection
core/.postman/manifest.json	tracked upstream collection state
core/source/.gitkeep	the fetched collection lands here
public/.github/workflows/ci.yml	docker build then node scripts/generate.mjs; triggers only on source/**, scripts/**, Dockerfile, connectors.config.json
public/.github/workflows/sync.yml	daily cron diffing the upstream collection and opening a PR

A hand-authoring repo drops all seven. What is left of the type overlay is
core/connectors/.gitkeep and core/README.md.tmpl — so choosing this type buys almost nothing,
while the scaffold output actively misleads: ci.yml never fires (none of its trigger paths ever
change), and sync.yml runs a daily cron against an unfilled sourceUrl.

Why hand-authoring isn't a fringe case

In PBNZ/sdp-on-prem-powerplatform it wasn't a preference, it was forced. The vendor's official
Postman collection is ~9 MB — over Power Platform's 1 MB import cap — and mostly example payloads,
modelling the API as raw requests rather than clean actions. Converting it mechanically produces
something that cannot be imported. See
ADR-0001.

That repo has run this way for four connectors / 55 operations, and the shape that emerged looks
reusable:

• A curated operation table in a small reviewable script that stamps the repetitive per-op
  boilerplate. Not a Postman conversion — the input is a hand-written spec, and the generated JSON
  stays the committed, reviewed artifact.
• A validation CI that is definition-shaped rather than pipeline-shaped: swagger-cli validate,
  the 1 MB import cap, apiProperties.json secured-parameter sanity, and generator-idempotency
  (run the generators && git diff --exit-code) so the committed JSON provably matches its source.
• An x-ms-* rules checker, because the Power Platform portal enforces rules generic Swagger
  2.0 validators pass silently. The one that cost real time: a parameter with
  x-ms-visibility: internal and a default must be required, or the portal refuses to save
  (PropertyMustBeRequired) and the runtime silently drops the header.

Suggested shape

Either a separate type (power-platform-connectors-handauthored) or a scaffold-time question —
"are these definitions generated from a Postman collection, or hand-authored?" — that swaps the
overlay. The hand-authored branch would ship the definition-validation CI instead of the generate
CI, and drop the Dockerfile / generator / config / .postman/ / source/ set.

If it's useful, the CI workflow and the two checker scripts are Apache-2.0 in
sdp-on-prem-powerplatform:
.github/workflows/validate.yml,
tools/check_pp_rules.py.

Context

This was noted at scaffold time in that repo's LESSONS.md and has sat unfiled since 2026-07-04;
filing it now while auditing the repo against 0.5.0. Related: the same audit found the type's
sync.yml/ci.yml omission had never been declared in the START-HERE map, which 0.5.0's
variance-declarations rule requires — that part was a downstream bug and is fixed.