+1 for the proposal. I find the current item-items functionality logical. "item" is used in leaf items, "items" is used in non-leaf items. Forcing a non-leaf root just so we always have "items" is overhead.
Svet. > On 20.06.2016 г., at 15:47, Aled Sage <aled.s...@gmail.com> wrote: > > Hi all, > > The YAML format for adding catalog items accepts several different ways of > defining them. This has led to our examples being inconsistent, our code more > complicated, and potential confusion for users when they see different things > that turn out to mean the same. > > I think we should standardise on one approach, and deprecate the other ways. > > --- > > _*Current Code*_ > > An example .bom file is shown below: > > brooklyn.catalog: > items: > - id: entity1 > version: "1.0.0" > itemType: entity > item: > type: org.apache.brooklyn.entity.machine.MachineEntity > > Variants: > > * If defining just a single item in the .bom file, you can optionally > miss out the "items". > * You can miss out the "itemType" - it will guess at it by trying to > treat it as an entity, a template, a location or a policy. The > default is "entity". > * You can include "services:" for entity or template types, or you can > miss it out if there is just one entity in the item. > * Similar to "services:", you can include "brooklyn.policies:" or > "brooklyn.locations:". > If itemType is missing, this helps to infer the type. If it does not > agree with itemType, then we add it as the item type and it will > fail later. > * You can define the item metadata at any level - it could be directly > under "brooklyn.catalog" (in which case it applies to all items), or > under a specific item (in which case it overrides any more general > metadata). > > > An example of a .bom for a single item is shown below: > > brooklyn.catalog: > id: entity2 > version: "1.0.0" > itemType: entity > item: > type: org.apache.brooklyn.entity.machine.MachineEntity > > > --- > > _*Proposal*_ > > I suggest we have the following stricter rules. Anything else is deprecated, > logging a warning. > > * Always include "itemType". > * For entity, policy and location: do not include "services:", > "brooklyn.policies:" or "brooklyn.locations:" - i.e. it will expect > exactly one type in the item. > * For template, always expect "services:" (even if there is just one > thing). This is consistent with the YAML required when deploying an > application. > * Always include "items", even if there is just one item in it. > (reasoning: we do not support "service" versus "services", so why > support "item"). > > > We should change the following (breaking backwards compatibility, because > it's really a bug): > > * If the itemType differs from the actual type of the item, then fail. > > Aled > > p.s. I'm in two minds about "item" versus "items": it is simpler with the > single item, and having "item" underneath "items" means it's not quite like > the "services" analogy. > >
