RE: [Proposal]: New schema for Invoices

What is the difference between Order and Invoice? With the use of orderStatus == OrderPaymentDue (or lack thereof for paid invoices/orders), it looks like I can specify the same things that I can with Invoice. How would a publisher know when to use one vs. the other?

One uniqueness I see is the addition of provider to Invoice, but it seems like it may have been an oversight that provider isn’t on Order and/or Offer. Or was it intentional?

Of the new properties, totalPaymentDue, minimumPaymentDue, accountId, scheduledPaymentDate, and maybe paymentStatus all seem like they would be good additions to Order.

payFromAccountId seems like it can be handled via the existing paymentMethod (e.g., set to http://purl.org/goodrelations/v1#DirectDebit) plus paymentMethodId (which would be the account ID from which to take the payment, right?).

Depending on what values we envision for paymentStatus, we may be able to model them with the existing orderStatus. Obvious ones such as “due” and “paid” could be covered. If we also want to cover terms like net-30, past due, in collection, etc., we may want to separate out paymentStatus from orderStatus, in which case I would think about deprecating the OrderPaymentDue status in favor of using a new paymentStatus property on Order.

billingPeriod is the one property that I don’t think fits neatly into Order. Maybe, for this, we should actually have a derived type from Order? If people like that idea, we could simply derive the new Invoice type from Order with the only difference being the presence of the billingPeriod property. If we do this, the linkage to Order (n/a – it’s the same thing) and Offer (already exists through acceptedOffer) is also handled. We may want to extend the range of orderedItem to include Service.
BTW, you have a typo on the label of some of the ranges (e.g., for totalPaymentDue), which are labeled as “Domain: “ instead of “Range: “

Thanks,
Tom

From: Vicki Tardif Holland [mailto:vtardif@google.com]
Sent: Monday, December 15, 2014 9:28 AM
To: Martin Hepp
Cc: W3C Web Schemas Task Force
Subject: Re: [Proposal]: New schema for Invoices


On Mon, Dec 15, 2014 at 12:09 PM, Martin Hepp <martin.hepp@unibw.de<mailto:martin.hepp@unibw.de>> wrote:
Thanks - such an entity was indeed missing. A few questions:

1. With invoice, do you mean a) a receipt of payment b) a document representing a payment request or c) the union of both. In other words, how is an invoice related to (1) an actual payment, (2) a legal obligation to pay a certain amount, and (3) an underlying transfer of rights that causes the obligation to pay a compensation?

A union of both. One might receive an invoice requesting payment and then a subsequent invoice with paymentStatus stating the payment was received.



2. How is an invoice linked to a) http://schema.org/Offer and b) the subtypes of http://schema.org/TradeAction, like
- http://schema.org/BuyAction

- http://schema.org/PayAction

- http://schema.org/RentAction

- http://schema.org/SellAction

- http://schema.org/TipAction



I can imagine invoices without either one, e.g. invoices without offer nor transaction for prepayments or advances.

But if the entities exist, they should be linkable.


Good point. In many cases, the original Offer is unknown, but if the Offer or Order is known, there should be a link. I can add the properties "paymentForOffer" and "paymentForOrder".




3. I think we should have a method for including a list of items in the invoice. One could define a new property "itemsIncluded" with an ItemList that links to entities of the type of http://schema.org/TypeAndQuantityNode.


If there is a link to the Offer, do you still need to list the items separately?


4. Currently, the support for modeling tax information in price information in schema.org<http://schema.org> and GoodRelations is pretty simple; we may want to expand this part and add it to Invoice, too, because e.g. the ability to expose VAT rates and absolute values may be very relevant for European users.

5. Also, we currently have no model for staged payments and financing in GoodRelations and schema.org<http://schema.org>; this will also touch Invoice (image a car invoice with a single down payment and four installments with individual due dates).

Yes, these can get complicated. It may be better to treat each installment as a separate invoice and link them together.

- Vicki


Vicki Tardif Holland | Ontologist | vtardif@google.com<mailto:vtardif@google.com>