First pass at handling this issue - Add ignoreMissingData query parameter.

When it comes to omitting these fields in the JSON:

- Omitting ``facetIds`` or ``metadataBlockNames`` causes the Dataverse collection to inherit the corresponding configuration from its parent.
- Omitting ``inputLevels`` removes any existing custom input levels in the Dataverse collection.
- Omitting the entire ``metadataBlocks`` object in the request JSON would exclude the three sub-objects, resulting in the application of the two changes described above.

To prevent these omissions from being removed and inherited from the parent you can add the query parameter ignoreMissingData=true

.. code-block:: bash

  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  export SERVER_URL=https://demo.dataverse.org
  export DV_ALIAS=dvAlias

  curl -H "X-Dataverse-key:$API_TOKEN" -X PUT "$SERVER_URL/api/dataverses/$DV_ALIAS?ignoreMissingData=true" --upload-file dataverse-complete.json

@qqmyers @stevenwinship @g-saracca

Regarding using one flag or two as an endpoint parameter. In JSF, facets are selected independently from metadata blocks. In fact, there are two separate flags in the database to manage this inheritance: https://github.com/IQSS/dataverse/blob/develop/src/main/java/edu/harvard/iq/dataverse/Dataverse.java#L183-L184

And look at JSF to see how we can select facets even from metadata blocks that aren’t selected:

I’m not sure if this behavior in JSF is intentional, but that’s how we replicated it in the SPA and the API.

For this reason, if we decide to modify the endpoint to explicitly indicate inheritance using flags, I would recommend providing two independent flags: one for inheriting metadata blocks and another for facets. This is because inheriting metadata blocks does not imply inheriting facets, as they are independent concepts (I understand that we aim to preserve this behavior to align with the goal of replicating JSF).

First pass at handling this issue - Add ignoreMissingData query parameter.

When it comes to omitting these fields in the JSON:

- Omitting ``facetIds`` or ``metadataBlockNames`` causes the Dataverse collection to inherit the corresponding configuration from its parent.
- Omitting ``inputLevels`` removes any existing custom input levels in the Dataverse collection.
- Omitting the entire ``metadataBlocks`` object in the request JSON would exclude the three sub-objects, resulting in the application of the two changes described above.

To prevent these omissions from being removed and inherited from the parent you can add the query parameter ignoreMissingData=true

.. code-block:: bash

  export API_TOKEN=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  export SERVER_URL=https://demo.dataverse.org
  export DV_ALIAS=dvAlias

  curl -H "X-Dataverse-key:$API_TOKEN" -X PUT "$SERVER_URL/api/dataverses/$DV_ALIAS?ignoreMissingData=true" --upload-file dataverse-complete.json

That could be another valid approach. Possibly simpler!

If we use 2 flags (1 for metadataBlocks and 1 for facetIds) how do we handle inputLevels? Do we need another flag or can we group inputLevels with facetIds or metadataBlocks?

If we use 2 flags (1 for metadataBlocks and 1 for facetIds) how do we handle inputLevels? Do we need another flag or can we group inputLevels with facetIds or metadataBlocks?

If you inherit metadata blocks from the parent, there is no need to set input levels manually. The input levels of the parent will automatically be applied when retrieving the metadata blocks and fields of the new Dataverse. Input levels should be sent if you are not checking the 'inherit metadata blocks from parent' and, of course, you want to customize input levels for a metadata block.

FWIW: I'm not sure I like the polarity of a ignoreMissingData=true flag - seems like a inheritMetadataSettingsFromParentIfMissing=true flag would be safer (though longer - not sure if there's a short way to say it). Even so, those are both implicit and cause the same Json to have different effects -
seems like a

metadataBlocks {
  "inheritMetadataBlocksFromParent":true,
  "inerhertFacetsFromParent":"true"
}

as an option in Json versus including the metadataBlockNames/inputLevels and facetIds fields would be clearer?

I agree with @GPortas that we follow the JSF behaviour, we just need now an extra tweak. I like @qqmyers idea about

metadataBlocks {
"inheritMetadataBlocksFromParent":true,
"inheritFacetsFromParent":"true"
}

This will mean that if inheritMetadataBlocksFromParent is true, even sending metadataBlockNames and inputLevels with some values, these two properties will be skipped. The same if inheritFacetsFromParent is true, even sending facetIds with values, they will be skipped.
Is that ok?
So that will be the only way to switch the collection to start using metadata blocks and/or facets from parent.

I'd suggest documenting it to say you can send the relevant flag or the corresponding list, but not both. In code, we could just check for the flags first and (as we often have done) ignore any other json that is irrelevant. If it's easy to reject the call when the user sends both a flag and a list - even better.