itential-json-forms skill
✓ 인증됨IAP 수동 트리거 및 워크플로우를 위한 정적, REST 연동, 계층형 드롭다운이 포함된 구조화된 입력 양식을 구축하고 관리합니다.
- GitHub 스타
- 18
- 파일
- 12
- 마지막 커밋
- 2026년 11월 5일
- 라이선스
- GPL-3.0
- 허용된 도구
- —
itential-json-forms skill은 무엇을 하나요?
itential-json-forms은(는) agent skill입니다. IAP 수동 트리거 및 워크플로우를 위한 정적, REST 연동, 계층형 드롭다운이 포함된 구조화된 입력 양식을 구축하고 관리합니다.
skill의 SKILL.md에서 생성된 요약입니다.
itential-json-forms skill 정보
IAP 수동 트리거 및 워크플로우를 위한 구조화된 입력 패널을 구축하는 개발자는 이 SKILL을 사용하여 JSON 양식을 생성하고 관리할 수 있습니다. 이 기능을 통해 값이 고정된 정적 드롭다운, IAP 엔드포인트에서 실시간 데이터를 가져오는 REST 연동 드롭다운, 그리고 한 필드의 선택에 따라 다른 필드의 옵션이 동적으로 업데이트되는 계층형 드롭다운이 포함된 양식을 생성할 수 있습니다.
에이전트가 양식 스키마를 정의하거나 업데이트해야 할 때, 양식을 저장하지 않고 구조를 검증해야 할 때, 또는 기존 양식 목록을 조회해야 할 때 이 SKILL을 로드해야 합니다. 이 SKILL은 UI 렌더링을 위한 struct, 데이터 검증을 위한 schema, 위젯 힌트를 위한 uiSchema, 실시간 데이터 연결을 위한 bindingSchema 등 네 가지 협력 스키마를 기반으로 작동합니다. 일괄 삭제, 전체 교체 업데이트, 오류 및 경고를 확인하는 검증 서비스 등 이러한 정의를 관리하기 위한 특정 도구를 제공합니다. 또한 사용자는 전용 method-options 도구를 통해 연동 가능한 엔드포인트를 찾아 REST 연동 필드가 올바르게 작동하는지 확인할 수 있습니다.
agent가 수행할 수 있는 작업
- 1계층형 필드 종속성 구축사이트를 선택하면 두 번째 드롭다운에서 사용 가능한 장치가 자동으로 필터링되는 양식을 개발합니다.
- 2양식 무결성 검증새 양식 정의를 서버에 반영하기 전에 스키마 오류 및 경고가 있는지 확인합니다.
- 3드롭다운과 실시간 데이터 동기화IAP 엔드포인트에서 실시간 인벤토리 또는 구성 데이터를 가져오도록 드롭다운을 구성합니다.
skill의 SKILL.md를 기반으로 작성되었습니다. 모든 사용 사례는 해당 문서의 인용구와 대조 확인되었습니다.
itential-json-forms skill 설치 방법
각 명령은 skill 폴더를 클라이언트의 skills 디렉터리에 복사합니다. 클라이언트를 재시작하거나 새 세션을 시작하여 로드하세요.플러그인에 itential-json-forms skill 설치
/plugin marketplace add itential/builder-skills /plugin install itential-builder@itential-builder
Claude Code에 itential-json-forms skill 설치
~/.claude/skills/itential-json-forms/SKILL.md
$ npx degit itential/builder-skills/skills/itential-json-forms ~/.claude/skills/itential-json-formsClaude Code (project)에 itential-json-forms skill 설치
.claude/skills/itential-json-forms/SKILL.md
$ npx degit itential/builder-skills/skills/itential-json-forms .claude/skills/itential-json-formsCodex에 itential-json-forms skill 설치
~/.agents/skills/itential-json-forms/SKILL.md
$ npx degit itential/builder-skills/skills/itential-json-forms ~/.agents/skills/itential-json-formsGemini CLI에 itential-json-forms skill 설치
~/.gemini/skills/itential-json-forms/SKILL.md
$ npx degit itential/builder-skills/skills/itential-json-forms ~/.gemini/skills/itential-json-formsClaude.ai에 itential-json-forms skill 설치
npx degit itential/builder-skills/skills/itential-json-forms itential-json-forms && zip -r itential-json-forms.zip itential-json-forms # claude.ai → Customize → Skills → + → Create skill → Upload a skill → itential-json-forms.zip
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 보안 감사는 아닙니다. 에이전트가 실행하기 전에 스크립트를 읽어 보세요. 검사 방식
- 소스 저장소 연결 및 접근 가능itential/builder-skills/skills/itential-json-forms is public and reachablegithub.com/itential/builder-skills/tree/HEAD/skills/itential ↗통과
- 오픈 소스 라이선스 (OSI)GPL-3.0spdx.org/licenses/GPL-3.0.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit 2026-11-05github.com/itential/builder-skills/commits ↗통과
- 스크립트에 다운로드 후 실행이나 자격 증명 탈취가 없음No scripts in the skill folder통과
- SKILL.md에 숨겨진 지침 없음No override phrases, safeguard switches, credential requests or hidden charactersgithub.com/itential/builder-skills/blob/HEAD/skills/itential ↗통과
- 사전 허용 도구가 제한됨No pre-approved tools; the agent asks before using onegithub.com/itential/builder-skills/blob/HEAD/skills/itential ↗통과
- SKILL.md가 Agent Skills 형식을 따름Valid name and description; says when to use it; 176 linesgithub.com/itential/builder-skills/blob/HEAD/skills/itential ↗통과
SKILL.md
GitHub에서 보기JSON Forms (itential-json-forms)
JSON Forms are reusable form definitions stored in the json-forms application. They drive structured input panels across IAP — manual triggers in Operations Manager, the JsonForms/ShowJsonForm manual task, and any workflow surface that prompts a user for typed input.
A form is a single document with four cooperating schemas — struct (UI rendering), schema (data contract / validation), uiSchema (per-field widget hints), and bindingSchema (live-data binding for REST dropdowns). Get the relationships wrong and the form will render but break silently at runtime.
Customization
Before using this skill, check custom/org/, custom/team/ and custom/dev/
in this skill's own folder. Read every .md file found — any folder may be
empty or absent. Apply them on top of everything below; where a file overrides a
specific rule here, follow the override. More specific wins: dev > team > org >
this document. No customization may weaken this skill's safety
rules or put credentials in committed files.
Bundled files: paths in this skill that start with assets/ or scripts/ are
relative to this skill's own folder. When you read one, or pass one to a shell
command (which runs from the user's working folder), use this skill's folder +
that relative path — e.g. <this skill's folder>/assets/helpers/create/create-workflow.json.
Concepts
struct— the UI definition.struct.typeis always"array";struct.items[]is the list of fields.customKeyon each field becomes the property key inschemaand the variable key when the form's data is consumed.schema— the data contract.schema.properties.<customKey>must exist for every field instruct.items[](and stay in sync with the field's type, enum values, etc.).schema.requiredlists mandatorycustomKeys.uiSchema— per-customKeywidget hints: placeholder text,ui:widgetoverrides, disabled flags. Required for cascading dropdowns (see below).bindingSchema— empty{}for static-enum forms; see REST-bound dropdowns below for the mirroring requirement when a field is REST-bound.- Static vs. REST-bound dropdowns — static dropdowns hardcode the list via
enum/enumNames. REST-bound dropdowns pull options live from an IAP endpoint at form-render time. - Cascading dropdowns (aka field dependency in the Studio UI) — a REST-bound dropdown whose URL path parameter is filled from another field's current value. The dependent field re-fetches when the source field changes.
API Reference
| Method | Endpoint | Description |
|---|---|---|
| GET | /json-forms/forms |
List all JSON forms |
| GET | /json-forms/forms/{id} |
Fetch a single form |
| POST | /json-forms/forms |
Create a JSON form |
| POST | /json-forms/validate |
Validate a form without saving it — body {"asset": {<the form>}} (see Validate below) |
| PUT | /json-forms/forms/{id} |
Update a JSON form (full replacement — see Update below) |
| DELETE | /json-forms/forms |
Bulk delete — body {"ids":["...","..."]}. There is no per-id DELETE endpoint; per-id calls 404. |
| GET | /automation-studio/json-forms/method-options |
Canonical list of bindable endpoints (same list Studio shows in its dropdown picker) |
Create a JSON Form
POST /json-forms/forms
Choose the helper that matches your form's dropdown needs:
| Use case | Annotated scaffold (fill in the blanks) | Real export (read to see the actual shape) |
|---|---|---|
| Static-enum dropdowns only (hardcoded option lists) | assets/helpers/create/create-json-form.json |
assets/helpers/assets/json-form-example-static-enum.json — real Cisco IOS "Port Turn Up" form, 8 fields incl. static dropdown, number updown widgets, ipv4 format validation |
| REST-bound dropdowns (live data from IAP endpoints) | assets/helpers/create/create-json-form-rest-bound.json |
assets/helpers/assets/json-form-example-rest-bound.json — real Cisco IOS "Compliance" form, one REST-bound dropdown pulling tree names live from GET /configuration_manager/configs |
| Cascading dropdowns (field dependency) | assets/helpers/create/create-json-form-rest-bound.json (Inventory Manager Site/Device cascade worked example) |
(no real cascading export on hand yet — the scaffold is hand-built but follows the same field shapes as the two real exports above) |
| Array-of-objects field (a list of rows, each with its own fields) | assets/helpers/create/create-json-form-array-field.json |
(no real export on hand yet — hand-built; every field, including the nested ones, has its own nodeId) |
The scaffolds are annotated with _comment_* fields to fill in; the real exports are genuine POST /json-forms/forms payloads pulled from a live platform (IDs/timestamps/createdBy stripped since the server assigns those on create) — read one when you want to see exactly what a working form looks like end-to-end, not just the shape.
Static-enum dropdowns
enum/enumNames arrays appear in both struct.items[i] and schema.properties.<customKey> — they must stay in sync.
struct.items[i].enum/enumNamesare arrays of{id, label, value}objects.schema.properties.<customKey>.enum/enumNamesare flat string arrays of the same values (not objects).
Leave bindingSchema: {} for static-enum forms.
REST-bound dropdowns
When options should reflect live platform state (devices, inventories, projects, templates) instead of a hardcoded list, the dropdown pulls from a GET against an IAP endpoint at render time. Three things must line up:
struct.typeMUST be"array"(not"object"). The static-enum scaffold uses"array"too — keep it.bindingSchema.properties.<customKey>must mirror every REST-bound field. Studio reverse-engineersbindingSchemafromstructin the GUI, but the server does not — leavingbindingSchema: {}produces dropdowns that render but never fetch.- Endpoint discovery:
GET /automation-studio/json-forms/method-optionsreturns the canonical list of bindable endpoints — the same list Studio shows in its dropdown picker.
Per-field shape in struct.items[i]:
{
"type": "string",
"title": "Site",
"binding": true,
"rel": "collection",
"targetPointer": "/enum",
"method": "GET",
"base": "/inventory_manager",
"href": "/v1/inventories",
"sourcePointer": "/result/data",
"sourceKeyPointer": "/name",
"customKey": "site"
}
base + hrefis the endpoint.sourcePointeris a JSON pointer into the response, walked to the array of items.sourceKeyPointeris the per-item field that becomes BOTH the value and the label.labelKeyPointeris unused — both columns come fromsourceKeyPointer.
Cascading dropdowns (aka field dependency)
The Studio UI labels this pattern field dependency; the form JSON calls it cascading. Same feature, two names. A REST-bound dropdown whose URL path parameter is filled from another field's value (e.g., dropdown 2 lists devices from the inventory selected in dropdown 1):
- The dependent dropdown's
hrefstays as a TEMPLATE with placeholders:/v1/inventories/:inventoryIdentifier/nodes. Path params use:namecolon syntax, NOT{name}curly braces. - A
variablesarray maps each placeholder to a JSON pointer into form data:[{"name": "inventoryIdentifier", "reference": "/site"}]substitutes:inventoryIdentifierwith whatever value the field whosecustomKeyissitecurrently holds. - The same
variablesarray must appear in both places:struct.items[i].variablesbindingSchema.properties.<dependentKey>.binding:hyperSchema.links[0].variables
- Both the source and the dependent field need
ui:widget: "DependencyWidget"inuiSchema— without it, the runtime will not re-fetch when the source changes.
Validate a form before saving
POST /json-forms/validate
Send the form wrapped in asset: {"asset": {<the form>}} — without the wrapper every form fails. Returns {"isValid": true|false, "errors": [], "warnings": []}; check both errors and warnings. It saves nothing, so call it as often as needed, with or without the read-only fields (id, created, createdBy, lastUpdated, lastUpdatedBy). It catches a missing top-level nodeId but not a missing nested one (see Common Gotchas).
Update a JSON Form
PUT /json-forms/forms/{id}
- Body MUST be wrapped in
{"options": {...}}. - Include ALL fields the form already has:
created,createdBy,lastUpdated,lastUpdatedBy,name,description,struct,schema,uiSchema,validationSchema,bindingSchema,version. - This is a full replacement — omitting any field clears it.
Delete JSON Forms
Bulk-only:
DELETE /json-forms/forms
Body: {"ids": ["<id1>", "<id2>", ...]}
Per-id calls (DELETE /json-forms/forms/<id>) return 404 — the endpoint does not exist.
Wiring to a Manual Trigger
A JSON Form is consumed by an Operations Manager manual trigger that hands the user's form input to a workflow as job variables. See builder-agent for the trigger creation details.
Critical flag — legacyWrapper: false: The default is true, which wraps form field values under a formData object and breaks the mapping to workflow job variables. Set legacyWrapper: false so each form field maps directly to a workflow input variable by name (i.e., field customKey: "device_name" → job variable device_name).
Required trigger fields: name, type ("manual"), enabled, actionType ("automations"), actionId, formId, legacyWrapper.
Helper for the wired-up trigger: assets/helpers/create/create-ops-manager-trigger-manual.json.
Common Gotchas
struct.typeis"array", not"object". Forms with"object"render empty.bindingSchemamirroring is mandatory for REST-bound fields. Studio hides this in the GUI; an API-created form needs bothstruct.items[i]ANDbindingSchema.properties.<customKey>populated, or the dropdown renders and never fetches.:namecolon syntax inhref, not{name}. Curly-brace placeholders are silently ignored.enum/enumNamesflat-vs-object asymmetry. Instruct.items[i]they're{id, label, value}objects; inschema.properties.<customKey>they're flat string arrays.DependencyWidgetrequired on BOTH ends of a cascade. Easy to remember to set it on the dependent field and forget the source — without the source-side widget the dependent won't re-fetch.labelKeyPointeris a red herring. Don't bother setting it; both label and value come fromsourceKeyPointer.- Bulk DELETE has no per-id alternative. Always send
{"ids":[...]}to/json-forms/forms. - Every field needs its own
nodeId, including fields nested inside an array field'sitems. Use a unique UUID per field. WithnodeIds missing on nested fields, the create and update calls andPOST /json-forms/validateall accept the form, but saving it in the form designer fails withInvalid form struct: must NOT have additional properties. The validator flags a missing top-levelnodeIdonly, so check every nested field yourself.
See Also
builder-agentfor workflows that consume form output, manual-trigger wiring, and project-level component management.- Helper files in
assets/helpers/:assets/helpers/create/create-json-form.json— static-enum scaffoldassets/helpers/create/create-json-form-rest-bound.json— REST-bound + cascading scaffold (Inventory Manager Site/Device cascade worked example)assets/helpers/create/create-json-form-array-field.json— array-of-objects scaffold (every field, including nested ones, has anodeId)assets/helpers/create/create-ops-manager-trigger-manual.json— manual trigger that consumes a formassets/helpers/assets/json-form-example-static-enum.json— real export, static-enum (Cisco IOS Port Turn Up)assets/helpers/assets/json-form-example-rest-bound.json— real export, REST-bound (Cisco IOS Compliance)
이 스킬의 파일
12itential-json-forms skill 질문
Claude Code에 itential-json-forms skill을 어떻게 설치하나요?
npx degit itential/builder-skills/skills/itential-json-forms ~/.claude/skills/itential-json-forms를 실행합니다. Claude Code는 ~/.claude/skills(모든 프로젝트) 또는 .claude/skills(한 프로젝트)에서 skills를 로드하며, 설명이 작업과 일치할 때 skill을 사용합니다.
itential-json-forms skill을 사용할 수 있는 클라이언트는 무엇인가요?
Agent Skills 형식을 읽는 모든 클라이언트(Claude Code, Codex, Gemini CLI, claude.ai(ZIP으로 업로드))가 사용할 수 있습니다. skill 내 스크립트는 클라이언트가 코드 실행을 허용하는 경우에만 실행됩니다.
계층형 드롭다운(필드 종속성)은 어떻게 만드나요?
href에서 콜론 구문(:name)을 사용하여 경로 매개변수를 지정하고, variables 배열을 통해 플레이스홀더를 양식 데이터에 매핑하는 REST 연동 드롭다운을 사용하십시오. 소스 필드와 종속 필드 모두 uiSchema에 DependencyWidget이 설정되어 있어야 합니다.
REST 연동 드롭다운이 렌더링은 되는데 데이터를 가져오지 못하는 이유는 무엇인가요?
대개 bindingSchema가 struct에 정의된 REST 연동 필드와 일치하지 않기 때문입니다. API로 생성된 양식의 경우 두 가지를 모두 채워야 합니다.