[Copilot]

New-CloudEvent, Set-CloudEventData, and Set-CloudEventJsonData lacked a parameter for setting the CloudEvents dataschema attribute.

• API: Add optional -DataSchema to all three cmdlets, accepting an absolute URI.
• Compatibility: Preserve an existing schema when data setters omit the parameter.
• Coverage and docs: Add regression tests for assignment, preservation, and invalid URIs; document the parameter and usage.

$cloudEvent | Set-CloudEventJsonData `
    -Data @{ 'Foo' = 'Hello' } `
    -DataSchema 'https://example.com/schema.json'

• Fixes [BUG] There appears to be no way to set the DataSchema attribute  #55

[duglin]

@oising look ok to you?

[duglin]

@copilot please fix the CI issues

[oising]

@oising look ok to you?

Looking... It seems there is no binding-by-property-name configured on the parameter. I'm looking at the suite as a whole to see if this was ignored en-masse

[oising]

@oising look ok to you?

Lgtm

Room for improvement but not in this PR

[duglin]

You sure? We could ask copilot to improve it

[oising]

You sure? We could ask copilot to improve it

Well okay, hold off until tomorrow and I'll give you some hints for the robot

[duglin]

@oising merge or wait?

[oising]

@oising merge or wait?

Reviewing now...

[oising]

@oising merge or wait?

I went through the current design with copilot and instructed it on how to have better cohesion between commands as well as improving the ux/dx, and I came up with this plan -- it wouldn't strictly be breaking, but I would be inclined to bump a minor version at least:

Plan: Pipeline binding improvements for CloudEvents.Sdk

Current state (src/CloudEventsPowerShell/CloudEvents.Sdk.psm1)

• 9 functions: New-CloudEvent, Set-CloudEvent{,Json,Xml}Data, Read-CloudEvent{,Json,Xml}Data, ConvertTo-HttpMessage, ConvertFrom-HttpMessage.
• Only -CloudEvent has ValueFromPipeline. No parameter uses ValueFromPipelineByPropertyName (ConvertTo-/ConvertFrom-HttpMessage set it explicitly to $false).
• No [OutputType], no [Alias], no parameter sets. Output is emitted with Write-Output.

Output → input cohesion gaps

• ConvertTo-HttpMessage emits {Headers, Body}, but ConvertFrom-HttpMessage can't take it from the pipeline.
• Invoke-WebRequest/Invoke-RestMethod responses expose Headers and Content. Body doesn't match Content, so nothing binds.
• ConvertTo-HttpMessage output can't be piped into Invoke-WebRequest. This is acceptable, but splatting should be documented.
• New-CloudEvent parameters (Type/Source/Id/Time/DataSchema) mirror CloudEvent property names but can't take objects (CSV rows, other events, custom objects) from the pipeline.
• Set-CloudEvent*Data can't take -Data from the pipeline.
• Reading from one event and writing to another needs a manual step.

Bugs coupled to parameter metadata

• Set-CloudEventData:
  • -DataContentType is a [string] that is never validated or converted.
  • The ContentType object built with New-Object is unused.
  • It throws when -DataContentType is omitted.
  • The raw string is assigned to $cloudEvent.DataContentType.
• Set-CloudEventXmlData: -AttributesKeysInElementAttributes is a mandatory [bool]. Changing it to a switch would be breaking, so it is deferred.
• Validation attributes are inconsistent (ValidateNotNullOrEmpty vs ValidateNotNull). -Body on ConvertFrom-HttpMessage is untyped.

Improvement list (non-breaking unless noted)

1. ConvertFrom-HttpMessage
   • Add ValueFromPipelineByPropertyName = $true to -Headers and -Body.
   • Add [Alias('Content')] on -Body.
   • Accept [System.Collections.IDictionary] for -Headers, a superset of hashtable that handles the Dictionary<string,string[]> from Invoke-WebRequest in PS7.
   • Result: ConvertTo-HttpMessage | ConvertFrom-HttpMessage and Invoke-WebRequest … | ConvertFrom-HttpMessage both work.
   • Positional and named usage stays identical.
2. ConvertTo-HttpMessage
   • Remove the explicit ByPropertyName = $false.
   • Add [OutputType] and a PSTypeName (e.g. CloudEvents.HttpMessage) on the output so it is discoverable.
   • Emit the same Headers/Body properties.
3. New-CloudEvent
   • Add ValueFromPipelineByPropertyName = $true on Type, Source, Id, Time, DataSchema.
   • Enables Import-Csv | New-CloudEvent and event-to-event cloning.
   • Make -Id and -Time optional, defaulting to [guid]::NewGuid() and the current time. This is additive and doesn't break existing callers.
   • Add [OutputType([CloudNative.CloudEvents.CloudEvent])].
4. Set-CloudEventData / Json / Xml
   • Add ValueFromPipelineByPropertyName to -Data, -DataContentType and -DataSchema (Json/Xml: -Data and -DataSchema).
   • Keep -CloudEvent as ValueFromPipeline, so by-value binding wins for CloudEvent input.
   • Decision: -Data binds by property name. Mitigate the case where a piped CloudEvent binds its own Data (via parameter sets or guard logic) and cover it with a test.
5. Read-CloudEvent*Data
   • Add [OutputType] (object / hashtable / etc.).
   • Add ValueFromPipelineByPropertyName to -CloudEvent, so wrapper objects with a CloudEvent property bind.
   • Make -Depth defaults consistent between Set and Read Json.
6. Consistent -CloudEvent parameter
   • Add [Alias('InputObject','Event')] in all 8 functions that take a CloudEvent.
   • Unify validation to [ValidateNotNull()].
   • Drop the redundant = $false attribute noise.
7. Pass-through: Set-* already emit the event, so no -PassThru is needed. Only simplify Write-Output if there is no behavior change.
8. Bug fixes (low risk)
   • Set-CloudEventData: only build the ContentType when -DataContentType is supplied, and assign the ContentType object.
   • Review -ConvertMode handling on Read-CloudEventXmlData.
9. Deferred (breaking, next major)
   • Make -AttributesKeysInElementAttributes a [switch].
   • Make -ConvertMode non-mandatory with a default.
10. Help and docs
    • Fix help inconsistencies (Add-CloudEvent*Data → Set-CloudEvent*Data, typos).
    • Add pipeline examples plus .INPUTS/.OUTPUTS.
    • Add pipeline recipes to the README.
11. Tests (test/unit/*.Tests.ps1)
    • Property-bound piping into New-CloudEvent.
    • ConvertTo-HttpMessage | ConvertFrom-HttpMessage round trip.
    • An IWR-shaped object (Headers, Content) piped into ConvertFrom-HttpMessage.
    • Set-*Data with Data/DataContentType bound by property name.
    • A regression test for the Set-CloudEventData content-type bug.
    • Run with test/RunTests.ps1.

Test policy

• Run the existing suite before changes (baseline) and after.
• If any existing test breaks because of a behavioral change, document it (test name, old vs new behavior, reason) in the PR description / CHANGELOG notes and in the final summary.
• Add new, independent Pester tests (self-contained, no shared state or ordering dependence) for every improvement.

Todos

1. Implement items 1–2 (HTTP cohesion).
2. Implement item 3 (New-CloudEvent).
3. Implement item 4 (Set-* data).
4. Implement items 5–6 (Read-*, aliases, validation, OutputType).
5. Fix the item 8 bugs.
6. Update docs and help (item 10).
7. Add tests (item 11) and run the unit suite before and after.

Decisions made

• -Data on Set-CloudEvent*Data accepts pipeline-by-property: yes.
• New-CloudEvent -Id/-Time auto-default: yes.
• New output type name CloudEvents.HttpMessage: proposed, not yet confirmed

I think you'll probably agree that this is worth its own PR.

[oising]

See plan.

[duglin]

@oising yes different PR, but I also am not sure I'm qualified to agree (or disagree) with the plan. My goal in getting involved here was to see if I can help unblock some easy issues/PR with the help of copilot. Adding brand new features w/o me really understanding the SDK is kind of risky (and i don't have the time to deep dive into it).

If I'm following, the analysis identified a couple of bugs in the current stuff, and those seem like things that are worth looking into even w/o the rest of the stuff. Would you agree?

Checkout: #58 - do you agree with the sentiment that the need for the SDK is minimal (at best)?

My current thinking... get copilot to fix the existing bugs you identified and then wait for some signs of life before we do a ux/dx change. WDYT?

[duglin]

To be clear, the two bugs are:

• Set-CloudEventData  throws an error when  -DataContentType  is omitted.
• Set-CloudEventData  builds a ContentType  object and then never uses it.

[oising]

@oising yes different PR, but I also am not sure I'm qualified to agree (or disagree) with the plan. My goal in getting involved here was to see if I can help unblock some easy issues/PR with the help of copilot. Adding brand new features w/o me really understanding the SDK is kind of risky (and i don't have the time to deep dive into it).

If I'm following, the analysis identified a couple of bugs in the current stuff, and those seem like things that are worth looking into even w/o the rest of the stuff. Would you agree?

Yes, agree.

Checkout: #58 - do you agree with the sentiment that the need for the SDK is minimal (at best)?

It's hard to tell - in its current form, it's already a fairly simple SDK that doesn't add a great deal of utility, IMO. It also doesn't follow a lot of the conventions for making functions/cmdlets composable: i.e. you should be able to pipe the output of one directly or indirectly into another without having to manually construct intermediate, temporary objects to compensate for mismatched or missing property/type bindings, assuming they cover the same surface area/functionality. An example of this would be how you can do the following:

ps> dir foo.txt | cat
This is the content!

The reason this works is because cat (a.k.a. get-content has a -LiteralPath property that binds by-name to the Path property on incoming piped objects.)

My current thinking... get copilot to fix the existing bugs you identified and then wait for some signs of life before we do a ux/dx change. WDYT?

Yes to fixing the current bugs. As for waiting, we could, but we might be in a chicken and egg situation. Maybe nobody uses it because it doesn't get much love and/or isn't very composable (as it stands.) I am happy to put some work into bringing it up to date. I am a ten-year powershell MVP (got some work in books, https://www.amazon.ca/PowerShell-Deep-Dives-Jeffery-Hicks/dp/1617291315 ) and work in distributed systems design, so I'm very familiar with cloudevents and related things.

[duglin]

@oising if you're willing to take on the task of bringing it up to where you think it needs to be, then that would be great. Obviously, it would be best to not break existing users, but we can always discuss that as we go along.

For now I'll merge this PR and open an issue for the bugs and the proposed changes in: #59 (comment)